getFileName and getAbsoluteFileName syntax

You can use the getFileName and getAbsoluteFileName methods to return the name of a specific file in the spool directory. This is useful because RICOH ProcessDirector assigns a unique job number for each job and includes the job number in file names. The main difference between the two methods is that getAbsoluteFileName fails if the specifically requested file does not exist; getFileName can return the name of an alternate spool file.

To use the RICOH ProcessDirectorgetFileName method or the getAbsoluteFileName method, use symbol notation to refer to them as RICOH ProcessDirector symbol formulas. Use one of these syntaxes:

Syntax 1, single search:

${getFileName(UsageKeyword, DatatypeKeyword, FileaccessKeyword)}

${getAbsoluteFileName(UsageKeyword, DatatypeKeyword, FileaccessKeyword)}

Syntax 2, iterative search:

${getFileName(UsageKeyword, (DatatypeKeyword1, DatatypeKeyword2...), 
FileaccessKeyword)}

${getAbsoluteFileName(UsageKeyword, (DatatypeKeyword1, 
DatatypeKeyword2...), FileaccessKeyword)}

where:

UsageKeyword
A case-sensitive keyword that identifies the usage type of the spool file. The values that authorized users can specify are the same values that the usage-type portion of the spool file name can contain. For example, you can specify these RICOH ProcessDirector-supplied keywords: aiwlist, control, overrides, or print. You can also specify your own user-defined keywords.
DatatypeKeyword or (DatatypeKeyword1, DatatypeKeyword2...)
A case-sensitive keyword that specifies the datatype of the spool file. The values that authorized users can specify are the same values that the datatype portion of the spool file can contain. For example, you can specify RICOH ProcessDirector-supplied keywords, such as jdf, pdf, or gif. You can also specify your own user-defined keywords.

If you want RICOH ProcessDirector to continue to search for another spool file if it does not find a spool file of the initial type, you can specify multiple datatype keywords. Separate them with commas and enclose them in parentheses. For example:

${getFileName(UsageKeyword, (print, pdf), FileaccessKeyword)}

In this example, the getFileName method first looks for a spool file with a datatype of print. If it does not find a matching spool file name, it looks for a spool file with a datatype of pdf. If it still does not find a matching spool file name, it looks for a spool file with a datatype of unknown. If that spool file does not exist, RICOH ProcessDirector issues an error message.

Note: The processing point at which RICOH ProcessDirector attempts to resolve the name of the file determines whether the method locates the file. If the workflow includes the SetJobPropsFromTextFile step, use the getAbsoluteFileName method instead of the getFileName method. The SetJobPropsFromTextFile step tries to resolve the file name that the getFileName method represents immediately after the input device creates the job, and not all spool files are available at that point in processing. RICOH ProcessDirector does not try to resolve the file name that the getAbsoluteFileName method represents immediately after job creation.

You can also specify multiple datatype values with the getAbsoluteFileName method, such as:

${getAbsoluteFileName(UsageKeyword, (pdf, postscript, text), 
FileaccessKeyword)}

The getAbsoluteFileName method looks for spool files in the same manner as the getFileName method, with one exception. If no spool files exist with any of the specified datatypes, the default is that the getAbsoluteFileName method does not look for a spool file with a datatype of unknown.

FileaccessKeyword
The file-access keyword, which is either read or write, specifies whether the external program reads the file from the spool directory or writes the file to the spool directory. RICOH ProcessDirector creates files in subdirectories of the spool directory, depending on whether the external program reads or writes a file:
/checkpoints subdirectory
When the external program makes changes to the file through a write operation, RICOH ProcessDirector moves the original version of the file to this subdirectory. If an authorized user subsequently requests a process-again action, RICOH ProcessDirector can restore the original spool file from the /checkpoints subdirectory. This makes sure that the external program has the same input available for its write operation as the first time that it processed the file.
/tmp subdirectory
When the external program creates a new file, RICOH ProcessDirector stores the new file in this subdirectory until the external step that calls the external program completes. When the step completes, RICOH ProcessDirector moves the new file to the spool directory.
Note: External programs that create child jobs must write them to the /children subdirectory of the spool directory for the job. The file name of the child job that the external program creates must be in this format: 
JobNumber.Usagetype.Datatype,ChildGroupID,Job.JobType=JobType
The ChildGroupID must be the same for all files associated with a single child job. If the external program generates more than one child job, it must increment the ChildGroupID for each set of files associated with a new child job.

The external program appends ,Job.JobType= to the file name, which is the database name for the workflow property. JobType value is the name of the workflow that the child job requires; this workflow must exist and it must be enabled.

getFileName and getAbsoluteFileName read examples

All of these examples use the spool directory:

  • /aiw/aiw1/spool/default/10000006 (Linux)

The spool directory contains these spool files:

10000006.banner_attributes.text
10000006.control.text
10000006.overrides.text
10000006.print.pdf
10000006.print.unknown
10000006.resources.pdf
10000006.resources.log
10000006.resources.outlines

For the purpose of these examples, the value of the Input data stream job property was not set through any manner, such as through a job default in the workflow or a detection step. Therefore, a spool file with a datatype of unknown is present in the spool directory:

  • To return the path and name of the control file for the job, which is /aiw/aiw1/spool/default/10000006/10000006.control.text, so that the external program can do a read operation on the file: 
    ${getFileName(control, text, read)}

${getAbsoluteFileName(control, text, read)}
  • To return the path and name of the input file for the job, which is /aiw/aiw1/spool/10000006/10000006.print.unknown, so that the external program can do a read operation on the file: 
    ${getFileName(print, unknown, read)}

${getAbsoluteFileName(print, unknown, read)}

This examples use the spool directory:

  • /aiw/aiw1/spool/default/10000009

The spool directory contains these spool files:

10000009.banner_attributes.text
10000009.control.text
10000009.overrides.text
10000009.print.ps
10000009.resources.pdf
10000009.resources.log
10000009.resources.outlines

In this example, the type of the input data stream was detected and 10000009.print.ps is the copy of the original input file. To search for an input file in one of the supported PostScript formats:

${getFileName(print, (pdf, ps), read)}

${getAbsoluteFileName(print, (pdf, ps), read)}

Both methods first look for a spool file with the name 10000009.print.pdf. Because that spool file is not present, the methods continue to look for a spool file with the name 10000009.print.ps.

getFileName and getAbsoluteFileName write examples

All of these examples use the spool directory:

  • /aiw/aiw1/spool/default/10000006
  • To set up for a write operation by an external program that writes a new statistics record file to the spool directory: 
    ${getFileName(statistics, record, write)}

${getAbsoluteFileName(statistics, record, write)}

    RICOH ProcessDirector provides the external program with the path and file name /aiw/aiw1/spool/default/10000006/10000006.statistics.record.

  • To set up for a write operation by an external program that updates the PDF print file in the spool directory: 
    ${getFileName(print, pdf, write)}

${getAbsoluteFileName(print, pdf, write)}

    RICOH ProcessDirector checkpoints a file with the name 10000006.print.pdf, if it exists, into the checkpoints subdirectory of the spool directory for the job.

    RICOH ProcessDirector also provides the external program with the path and file name /aiw/aiw1/spool/default/10000006/tmp/10000006.print.pdf.

    • If the program fails, the spool directory for the job is unchanged because the external program wrote to a file that RICOH ProcessDirector moved to the /tmp subdirectory. RICOH ProcessDirector only moves the file to the spool directory if the external step that calls the external program completes successfully.
    • If the program succeeds, RICOH ProcessDirector moves the file from the /tmp subdirectory into the spool directory. If a file by that name already exists in the spool directory, RICOH ProcessDirector moves that file to the checkpoint subdirectory, then moves the newly created file from /tmp to the spool directory for the job.

Parent topic: Using RICOH ProcessDirector methods