mvsprsd utility: starts the MVS download receiver daemon

Syntax

mvsprsd -pPortNumber -d FileSystem [-d FileSystem ...] [n -1] 
[-x ShellScript] [-X Additional exit parameters] [-q destination] [-k] [-B] 
[-H HostCodePage] [-L LocalCodePage][-t] [-w] [-e]

Description

Use the mvsprsd utility to start the MVS Download Receiver daemon. This daemon receives the data that Download for z/OS sends from the Job Entry Subsystem (JES) spool on an MVS system.

You can specify that the mvsprsd daemon starts whenever the system starts by including the mvsprsd command in one of the files that are executed when the AIX or Linux operating system is initialized. The two types of files that are read during AIX or Linux initialization are /etc/rc files and the /etc/inittab files.

If the mvsprsd daemon stops running for some reason, you can restart it by issuing this command:

/usr/lpp/psf/bin/mvsprsd -p PortNumber -d FileSystem -x ShellScript
   -q destination -k

If your job does not print on InfoPrint, you might be able to restart the shell script process with the downloaded file and downloaded print-options string. If you specify the -k flag on the print command, you can use this command to restart the shell script with its required parameter list:

/usr/lpp/pd/bin/mvsprpsm.sh FileName.PRD "$(cat string.JCL)" 
destination

Flags

The mvsprsd daemon utility uses these flags:

-pPortNumber

Specifies the socket port number for the daemon in the valid range (5001-64000). Do not use 8251 and 8253, which are used by InfoPrint for the PCL and PostScript data transforms. The port number must be the same as the port number specified in the routing-control data set used by Download for z/OS.

-dFileSystem

Specifies a file system where InfoPrint stores the received file until the shell script you specify in the -x flag processes and deletes the file. The mvsprsd daemon must have write permission for the file system.

You must specify at least one file system. You can specify up to ten file systems. If you specify more than one file system, the file system having the most available space is used. To specify more than one file system, specify the entire flag again:

-d FileSystem1 -d FileSystem2 ...

-n 1

If you are working with multiple data set support, you must specify -n 1 when you start the mvsprsd daemon on AIX or Linux. The -n 1 option restricts the mvsprsd daemon to receive one data set at a time.

If you did not previously specify -n 1 and you received multiple files concurrently, you might wish to start more than one instance of the mvsprsd daemon (using different port numbers) and configure new Download for z/OS printers on MVS to communicate with them.

For more information about the limitations of multiple data set support with Download for z/OS, see the chapter entitled “Printing data sets from an MVS system through MVS Download” in the RICOH InfoPrint Manager for AIX: Procedures or RICOH InfoPrint Manager for Linux: Procedures.

Note: If you enable multiple data set support and you need to configure multiple Download for z/OS FSAs, you must have one mvsprsd daemon/receiver for each Download FSA that is submitting jobs to the InfoPrint Manager server. If you do not do this and two Download for z/OS FSA systems send jobs at the same time, the job data sets can become intermingled and errors or incorrect output can result.

-xShellScript

Specifies the complete path name and file name for the shell script that the daemon executes to process the files sent by Download for z/OS. You can specify the file name of the shell script without the path name and it will default to the /usr/lpp/pd/bin path.

The daemon forks a child process to execute the shell script after each successfully received file. If you do not specify the path name of a shell script, the received files are not printed and remain on the file system.

InfoPrint provides a shell script, mvsprpsm.sh, which submits a file to the pdpr command for printing and deletes the file if the file prints successfully. This shell script is installed in the /usr/lpp/pd/bin directory.

-XAdditional exit parameters

• If you are using custom exits, consult with the person responsible for the custom exits to determine what to enter here.
• With InfoPrint Manger for AIX version 4.2, there are scripts that support additional exit parameters. These parameters are not supported on previous versions of the InfoPrint Manager script. They are not supported when custom scripts are used. The options are specified on the –X parameter of mvsprsd and have this syntax:

  failed_job=discard | print

  This parameter only has an effect when the AFP Download Plus is used. The parameter values have this meaning:

  discard

  If AFP Download Plus detected an error in any file in the job, discard the entire job. This is the same behavior as Download for z/OS multiple data set. This behavior is desirable to print outsource companies. This is the default if this keyword is not specified.

  print

  If AFP Download Plus detected an error in any file in the job, print the job including the error message provided by AFP Download Plus. The error messages provided by AFP Download Plus are printed where the file would normally be printed in the job. This is similar behavior to PSF for z/OS. This behavior is desirable for in-house print shops. AFP Download Plus provides a generic message, not the error messages that identify the cause of the failure.

  retry_count=n

  This parameter identifies the number of times the pdpr should be retried. The default value is 0. A value of 0 indicates the pdpr should not be retried. This parameter can have values from 0 to 32767.

  retry_interval=n

  This parameter identifies the time interval in seconds between pdpr retries. The default value is 60. A value of 0 indicates the pdpr should be retried immediately. This parameter can have values from 0 to 32767.

  Note:
  1. These options are only available if the provided script that is part of InfoPrint Manager version 4.2 is used. If an older InfoPrint Manager provided script is used they are ignored. If a custom script is used, these options should not be used.
  2. Using these options in combination with –n or –w might make the receiver inaccessible for longer periods of time to the host. You might need to modify the z/OS retry interval or count to compensate.

-qdestination

Specifies the name of the logical destination to which the shell script can submit the file. If you specify a logical destination, you should also specify the name of a shell script on the -x flag that the program uses to submit files to the logical destination.

If you specify this shell script on the -x flag, you must specify the -q flag or mvsprsd displays its command syntax and exits.

If you do not specify a logical destination name, the received files are not printed and remain on the file system.

-k

Specifies that the MVS print-options string is kept on the file system and can be used later for error recovery. If a file is transferred from MVS to AIX or Linux successfully, but does not print because of a problem, it is recommended that you specify this option so that the job can be resubmitted for printing from the operating system.

-B

Specifies that a limited EBCDIC to ASCII conversion should be performed on received MVS parameters. Upper and lowercase alphabetic, numerics, and a limited set of special characters are converted. All other characters are changed to an underscore character.

-H HostCodePage

Specifies the Host code page used when the JCL was submitted.

When you specify the -H flag, and the conversion from EBCDIC to ASCII fails, the receiver uses the default conversion table (inter-operable Latin-1 characters).

-t

Specifies tracing. The trace file is named trace.log.port and is created in the working directory. Only one previous trace file is maintained, and it is called trace.log.BAK.port. The trace file is moved to the backup trace file when the file exceeds 10 MB in size at a document boundary.

If the provided shell script is used with the -x flag, the files passed to the script and the intermediate files generated by the script will not be deleted when the script completes processing. You must delete these files manually.

-L LocalCodePage

Specifies the Local code page where the MVS Download receiver is running.

When you specify the -L flag, you must also specify the -H flag.

When you specify the -H and -L flags, and the conversion from EBCDIC to ASCII fails, the receiver uses the default conversion table (inter-operable Latin-1 characters).

Note: When you specify the -B and -H flags, and optionally, the -L flag, together, and the code page conversion fails, the NLS characters in the JCL parameter values are converted to an underscore character (_) so that an incorrect character is not inserted into the DBCS einvironment.

-w

Specifies the script return code should be monitored. A zero return code from the script causes the daemon to indicate success to the mainframe. A non-zero return code from the script causes the daemon to indicate failure to the mainframe.

When –w is specified and the script reports an error on a file in an multiple data set job, the mainframe might retry the file. The script must be prepared to get the same file again. The script can either process it again or fail it.

In addition, any data written to stderr by the script might be provided to the mainframe with the failure indicator.

Note:
1. The -w option also implies the –n 1 option.
2. Use of the -w option degrades overall throughput of the receiver since the receiver maintains the connection with the mainframe until the script completes. Degradation depends on the length of time the script runs, whether the –n 1 option is currently being used and whether multiple FSAs send files to the daemon. Little or no degradation will be seen for customers who have a single FSA that sends jobs to the daemon and currently use the –n 1 option. The most degradation will be seen for customers who have multiple FSAs sending jobs to the daemon and do not currently use the –n 1 option.
3. For Download for z/OS and existing AFP Download Plus customers without the AFP Download Plus APAR OA15317, TCP/IP inactivity time-outs can occur between the mainframe and the daemon. Customers should make sure that their inactivity time-out settings are larger than the time it takes their script to run. Retry settings in the script can also increase the necessary time. For AFP Download Plus customers with the AFP Download Plus APAR OA15317, the TCP/IP inactivity time-out needs to be set above 90 seconds.
4. When both -w and –e are specified, messages generated by the script might be also provided to AFP Download Plus if requested by AFP Download Plus.

-e

Specifies internal errors or script errors be reported to AFP Download Plus for assistance in problem determination. By default, this function is turned off. The –e option on mvsprsd must be specified to report internal errors. In addition, the -w option must be specified to report script/exit messages.

Examples

1. To start an MVS Download Receiver daemon that stores files received from the JES spool on the /files1 or /files2 file system and executes the mvsprpsm.sh shell script, which submits the files to the serv2-lp logical destination, enter:

   mvsprsd -p 5400 -d /files1 -d /files2 -x mvsprpsm.sh -q serv2-lp

2. To have the same MVS Download daemon keep the MVS print-options string file(s), enter:

   mvsprsd -p 5400 -d/files1 -d/files2 -qserv2-lp -k

3. To have the error messages printed, enter:

   mvsprsd –p 6001 –q local –d /mvsd –x /usr/lpp/pd/mvsprpsm.sh 
   -X”failed_job=print”

4. To set the number of times that pdpr should be retried as four and the time interval between pdpr retries as 30 seconds, enter:

   mvsprsd –p 6001 –q local –d /mvsd –x /usr/lpp/pd/mvsprpsm.sh 
   -X”retry_count=4 retry_interval=30”

Suggested reading

• Print Services Facilities for z/OS: AFP Download Plus, S550-0433
• Print Services Facilities for Z/OS: Download for z/OS, S550-0429
• rc.iprsap utility: start SAP daemons on InfoPrint Manager for AIX or InfoPrint Manager for Linux
• rc.pd utility: restarts servers in InfoPrint Manager for AIX or InfoPrint Manager for Linux