File Path and Identifier Functions: Difference between revisions

From wiki.jriver.com
Jump to navigation Jump to search
No edit summary
 
(6 intermediate revisions by 3 users not shown)
Line 3: Line 3:
The functions in this section provide specific file-related information such as
The functions in this section provide specific file-related information such as
a file's name, path, volume, and other Media Center internal information.
a file's name, path, volume, and other Media Center internal information.

=== <span id="DBLocation">DBLocation(&hellip;)</span> ===
: Identifies a file's databases.

{{function description box
| name=DBLocation
| arguments=
| description=
[[#DBLocation|DBLocation()]] behaves exactly as [[#FileDBLocation|FileDBLocation(0)]], and takes no parameters, returning only a semicolon-separated list of formatted database names.

| examples=
See [[#FileDBLocation|FileDBLocation()]]
}}

=== <span id="Enviro">Enviro(&hellip;)</span> ===
: Returns a specified host system variable

{{function description box
| name=Enviro
| arguments=System_Variable
| description=
[[#Enviro|Enviro()]] will lookup a given system variable and return its full path or contents. Note that the function only requires the variable name, bookended % signs are not necessary.

| examples=
'''{{monospace|Enviro(SystemRoot)}}'''
: Returns the system folder, typically C:\Windows

'''{{monospace|Enviro(SystemDrive)}}'''
: Returns the drive the system is installed on, typically, C:
}}


=== <span id="FileDBLocation">FileDBLocation(&hellip;)</span> ===
=== <span id="FileDBLocation">FileDBLocation(&hellip;)</span> ===
Line 11: Line 41:
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>filedblocation(</b><i>format</i><b>)</b></span>
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>filedblocation(</b><i>format</i><b>)</b></span>
The [[#FileDBLocation|FileDBLocation()]] function returns identifiers in the specified <i>format</i> specified that indicate to which internal database(s) a file belongs.
The [[#FileDBLocation|FileDBLocation()]] function returns identifiers in the specified <i>format</i> that indicate to which internal database(s) a file belongs.
Media Center maintains several internal databases to track a file's disposition.
Media Center maintains several internal databases to track a file's disposition.
This function is primarily for technical use only, and will have little utility for most users.
This function is primarily for technical use only, and will have little utility for most users.
Line 87: Line 117:
<div style="text-align:right;">([[#top|Back to top)]]</div>
<div style="text-align:right;">([[#top|Back to top)]]</div>


=== <span id="FileKey">FileKey()(&hellip;)</span> ===
=== <span id="FileKey">FileKey(&hellip;)</span> ===
: Returns a file's unique internal identifier.
: Returns a file's unique internal identifier.


Line 93: Line 123:
|- id="FileKey" valign="top"
|- id="FileKey" valign="top"
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
! scope="row" style="background: #ecedf3; color: #111; border-style: solid; border-width: 2px 1px 0 2px; border-right: 1px solid #bbb;" width="100" | Description
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>filekey()(</b><b>)</b></span>
| style="background: #f9f9f9; color: #111; border-style: solid; border-width: 2px 2px 0 0" width="1200" | <span style="font-family: monospace,monospace; font-size:1em; color:#0f3f8d; font-size:110%"><b>filekey()</b></span>
The [[#FileKey|FileKey()()]] function returns the unique identifier associated with a file.
The [[#FileKey|FileKey()]] function returns the unique identifier associated with a file.
Media Center assigns a unique identifier to each file in the Library.
Media Center assigns a unique identifier to each file in the Library.
It is useful in expressions when referring to individual files is necessary.
It is useful in expressions when referring to individual files is necessary.
Line 104: Line 134:
|}
|}
<div style="text-align:right;">([[#top|Back to top)]]</div>
<div style="text-align:right;">([[#top|Back to top)]]</div>

=== <span id="FileLookup">FileLookup(&hellip;)</span> ===
: Looks up a file from its filename

{{function description box
| name=FileLookup
| arguments=Filename
| description=
[[#FileLookup|FileLookup()]] will lookup a file from a given filename, returning its assigned [[#FileKey]]

| examples=
'''{{monospace|FileLookup([filename])}}'''
: Returns the filekey of each file run against it.

'''{{monospace|FileLookup(C:\Track /(Test/))}}'''
: Returns the filekey of the specified file. Note that when entering the filename directly, any special characters ''must'' be escaped otherwise, the expression will break.
}}


=== <span id="FileName">FileName(&hellip;)</span> ===
=== <span id="FileName">FileName(&hellip;)</span> ===

Latest revision as of 08:39, 19 March 2021

The functions in this section provide specific file-related information such as a file's name, path, volume, and other Media Center internal information.

DBLocation(…)

Identifies a file's databases.
Description DBLocation()

DBLocation() behaves exactly as FileDBLocation(0), and takes no parameters, returning only a semicolon-separated list of formatted database names.

Examples See FileDBLocation()
(Back to top)   (Function index)

Enviro(…)

Returns a specified host system variable
Description Enviro(System_Variable)

Enviro() will lookup a given system variable and return its full path or contents. Note that the function only requires the variable name, bookended % signs are not necessary.

Examples Enviro(SystemRoot)
Returns the system folder, typically C:\Windows

Enviro(SystemDrive)

Returns the drive the system is installed on, typically, C:
(Back to top)   (Function index)

FileDBLocation(…)

Identifies a file's databases.
Description filedblocation(format)

The FileDBLocation() function returns identifiers in the specified format that indicate to which internal database(s) a file belongs. Media Center maintains several internal databases to track a file's disposition. This function is primarily for technical use only, and will have little utility for most users.

Available format values:

0Semicolon-separated list of formatted database names
1Numeric value of OR'd database bit flags

The table below provides common values output from FileDBLocation():

Database nameBit position
Main0
Playing Now1
CD2
Explorer3
Other (16)5
Other (6)6
Grouping7
Removed8
Podcast10
Other (4096)12
Stacks14
Category Images18
Bad19

Argument format is optional (defaults to 0).

Examples filedblocation()

For a file in the Main and Other (4096) databases, the result would be Main; Other (4096).

filedblocation(1)

The result from the same file would be 4096 (bit 0 and bit 12 set).

Additional Examples

Sample expression that uses FileDBLocation() to show a file's databases.
(Back to top)

FileFolder(…)

Returns the name of a file's parent.
Description filefolder(filepath, level)

The FileFolder() function returns parent sub-folder name for filepath. The level argument specifies which parent sub-folder name to return, working the filepath from right-to-left (i.e. bottom of the folder tree upwards to the top). A value of 0 specifies a file's immediate parent, 1 its grandparent, etc., up to the root of the filepath. A value of Unassigned will be returned when the specified level exceeds the root of the filepath.

Argument filepath is optional (defaults to [filename]).

Argument level is optional (defaults to 0).

Examples filefolder()

Returns the name of the file's parent folder.

filefolder([filename,0], 0)

Same as the previous example.

filefolder(c:\some\folder\for\a\file.ape, 2)

Returns the great grandparent sub-folder named folder.

filefolder(c:\some\other\folder\a\, 2)

Returns the folder named other. Notice the file name is not required in the filepath. FileFolder() works by looking from the end of the filepath until it finds a backslash \.

(Back to top)

FileKey(…)

Returns a file's unique internal identifier.
Description filekey()

The FileKey() function returns the unique identifier associated with a file. Media Center assigns a unique identifier to each file in the Library. It is useful in expressions when referring to individual files is necessary. Services such as MCWS use this value to reference a file.

Examples filekey()

Returns a integer value, such as 22029495, unique for each file in the Library.

(Back to top)

FileLookup(…)

Looks up a file from its filename
Description FileLookup(Filename)

FileLookup() will lookup a file from a given filename, returning its assigned #FileKey

Examples FileLookup([filename])
Returns the filekey of each file run against it.

FileLookup(C:\Track /(Test/))

Returns the filekey of the specified file. Note that when entering the filename directly, any special characters must be escaped otherwise, the expression will break.
(Back to top)   (Function index)

FileName(…)

Returns a file's name component.
Description filename(filepath, include suffix)

The FileName() function returns the file name part of filepath. Inclusion of the file's suffix depends on the include suffix argument.

0Suppress file suffix
1Include file suffix

Argument filepath is optional (defaults to [filename]).

Argument include suffix is optional (defaults to 1).

Examples filename(C:\Music\File.mp3)

The output is File.mp3.

filename(C:\Music\File 2.wav, 0)

The output does not include the file suffix, and is File 2.

filename()

Returns the value contained in the field [filename (name)].

(Back to top)

FilePath(…)

Returns a file's path component.
Description filepath(filepath)

The FilePath() function will return the path portion of the specified file path.

The filepath should be a rooted path. For Windows, this includes the drive letter or leading \\ for UNC paths. For *nix-based systems, this includes the root /. The field [filename (path)] is equivalent to FilePath(), and is generally preferred.

Argument filepath is optional (defaults to [filename]).

Examples filepath(C:\Music\File.mp3)

Returns C:\Music.

filepath()

Returns the value contained in the field [filename (path)].

(Back to top)

FileVolume(…)

Returns a file's volume name component.
Description filevolume(filepath)

The FileVolume() function returns the volume name component of the specified file path. The path should be a rooted path (see the same comment above for FilePath(). For *nix-based systems, the output is empty. The field [volume name] is equivalent to FileVolume(), and is generally preferred.

Argument filepath is optional (defaults to [filename]).

Examples filevolume(C:\Music\File.mp3)

Outputs C:.

filevolume()

Returns the value contained in the field [volume name].

(Back to top)