SNAPRSIM - SNA Printer Simulator Bruce Crabill University of Maryland http://www.umd.edu/ This package contains a VTAM application named SNAPRSIM (SNA PRinter SIMulator). SNAPRSIM will simulate a VTAM printer for things like CICS or IMS who only want to talk to VTAM printers. The current version supports LU 1 emulation using the basic set of SCS commands. It allows the captured output to be sent to a TCP/IP connected printer via LPR or other mechanism (the exact mechanism is beyond the scope of this program, this program simply deals with the problem of getting the VTAM output into a VM spool file so that it may be dealt with). This program is designed to run as a VM VTAM application under GCS. It talks to the MVS side thru VTAM cross-domain facilities. Since this program does run under GCS, it should be possible to port it to MVS (but the author is a VM bigot, so don't bug me to do it). See the file SNAPRSIM CONTENTS for a description of the various source files that make up the program. The program itself is fairly well documented, but I have also included a copy of the paper I presented at SHARE 83 on this program. It is in file SNAPRSIM PDF, and is an Adoboe Protable Document Format (PDF) file that was created by the Adobe Acrobat package. I haven't tried distributing documentation in this form before, so this will be an interesting experiment. The paper has a lot of detail about the program's structure and should be read by anyone thinking of using this program. Adobe is making PDF viewers available for Macintosh, DOS, Windows, and Unix (currently only Suns). They are currently available via anonymous FTP at ftp.adobe.com in pub/adobe/Applications/Acrobat. You probably should not down load the source unless you think you are really going to use it (and have the disk space for it). It currently consists of some 92 ASSEMBLE files with approximately 60000 records and some 30 MACRO files with approximately 5400 records. The object file in the form of a GCS LOADLIB is available. If you wish to build the code for the source, then you will need at least Assembler H (required by VTAM) and access to the VTAM, GCS, and CP MACLIBs (see UVPG EXEC for the GLOBAL MACLIB statement that was used to create the distributed LOADLIB, changes will probably be required for your local environment). UVPMK EXEC may be used to create the UVP LOADLIB. It will create the UVP MACLIB, assemble all the source files, and invoke the linkage editor to build the final LOADLIB. The code is designed to be run in a service machine that I have named SNAFU (you may change the service machine's name if you don't have a sense of humor). See SNAFU DIRECT for a sample directory entry for this service machine. This service machine must be listed in the AUTHUSER list in the GCS configuration file. This is due to SNAPRSIM issuing CP commands to define virtual printers and to SPOOL them as needed and to CLOSE them after each received print file. SNAPRSIM also uses STNSM and SSM instructions, which require virtual supervisor mode. The printer LUs must be defined to VTAM as application LUs. See APPLES VTAMLST for sample VTAM definitions. The included PROFILE GCS is a sample for the SNAFU service machine that will invoke the SNAPRSIM application. In the current version, SNAPRSIM takes all its parameters on the command line (luckily, GCS doesn't seem to limit the length of the command line (unlike CMS)). I hope to add support for a configuration file and for interactive commands, but this version is at least functional (and I've been promising to get this code out for years now as it is). In the current implementation, all LUs must be defined at application start time. Since this version does not have interactive commands, SNAPRSIM issues a replyable message during initialization. When this message is replied to, SNAPRSIM will terminate all active sessions and will clean up. You only need to do this if you want to be graceful about it, if you are shutting down the system anyways, you can just FORCE it if you want. SNAPRSIM is invoked under GCS by using the following commands: GLOBAL LOADLIB UVPSIM LOADCMD SNAPRSIM UVPSIM SNAPRSIM Where are one or more of the following: LUS=,..., - Specify the name of one or more LUs that we are to handle. The LUs specified must be type 1 LUs using SCS printer data streams. For example: LUS=TCPPRT01,TCPPRT02,TCPPRT03,TCPPRT04 specifies that the LUs TCPPRT01, TCPPRT02, TCPPRT03, and TCPPRT04 be used. Multiple LUS parameters may be specified. GENLUS=,, - Generate a set of LU names that we are to handle using the given pattern. is a decimal number that specifies the starting number that is used with the given pattern to generate the LU name. is a decimal number that specifies the number of LUs to generate. is the format string that defines the format of the LU names to be generated. This format string uses the PRINTF format control characters. For each name to be generated, BPRINTF is called with the current number (the numbers starting at ) as the argument to be inserted using either a decimal insertion (%d) or a hex insertion (%X). For example: GENLUS=1,4,TCPPRT%02d will generate the LU names TCPPRT01, TCPPRT02, TCPPRT03, and TCPPRT04. Multiple GENLUS parameters may be specified. DEST= - The userid that will receive the spool files that we create containing the VTAM printer data. This is normally the TCPPRT service machine. The default is '*'. This parameter will be ignored on any LUs that also has the SPLARGS parameter active when they were defined. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: DEST=TCPPRT ENCAP=YES|NO - The output spool files are to contain the raw data as received from VTAM using a simple encapsulation mechanism. If not encapsulated, then the received LU1 or LU3 data will be converted into a VM print spool file. The default is not to encapsulate the received data. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: ENCAP=YES The encapsulated data has the format of 'LU1' or 'LU3' (depending on the type of data being received), followed by a byte containing a binary value with the number of data bytes in the current record (not counting the four byte header), followed by the indicated number of data bytes. The length byte is needed because CP may trim trailing spaces when the record is written to the output spool file. IBUFSIZE= - The size, in bytes, of the input buffer used for the VTAM RECEIVE operations. The default size is 2048, but may be increased if the LOGMODE entry for the LUs support larger RU sizes. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: IBUFSIZE=4096 OBUFSIZE= - The maximum size of the records written to the output spool file. It must be between 5 and 132. The default is 132. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: OBUFSIZE=36 PAGESIZE= - When transforming the received data from VTAM into a proper VM print spool file, this is the number of printable lines to a page. The default is 66. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: PAGESIZE=88 MAXOVER= - When transforming the received data from VTAM into a proper VM print spool file, this is the maximum number of lines that may be overprinted. The default is 10. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: MAXOVER=2 INFMT=STANDARD|ALL - Specifies how the input data is to be interpreted. The following values are defined: STANDARD, only the "standard" printable EBCDIC characters in the X'40' to X'FF' range are printed. Other characters will cause a warning message to be issued (only once for the given character per print file) and the invalid character is replaced by a question mark in the generated output spool file. ALL, all characters in the X'40' to X'FF' range are considered to be valid. The default is STANDARD. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: INFMT=ALL OUTFMT=STANDARD|NOOPTIM|NOPAGEUP|NOMULTI|NOMULTI2|SIMPLE| SIMPLE2 - Specify any special handling that the output file is to be given. The following value are defined: STANDARD, perform the standard page crossing optimization. Normally, an output operation that crosses a page boundary using normal line advancing orders are changed into a page up followed by the appropriate spacing commands. NOOPTIM, disable the page crossing optimization. NOPAGEUP, the output file will not contain page up operations. The appropriate number of spacing commands will be used instead. NOMULTI, do not use spacing operations that move the paper by more than one line. NOMULTI2, like NOMULTI, except that the active of NOPAGEUP is also added. SIMPLE, use only the Write and Space 1 Line command, the Write Without Spacing command, and the Write and Skip to Channel 1 command. SIMPLE2, like SIMPLE, except that the action of NOPAGEUP is also added. The default is STANDARD. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: OUTFMT=NOOPTIM FIRSTFF=STANDARD|STRIP|FORCE - Controls how the initial page up of a print file is to be handled. The following values are defined: STANDARD, don't do anything special. STRIP, if the first byte of a print file is a Form Feed, then ignore it. FORCE, force the output file to start with a page up. The default is STANDARD. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: FIRSTFF=STRIP LASTFF=STANDARD|STRIP|FORCE - Controls how the final page up is to be handled. The following values are defined: STANDARD, don't do anything special. STRIP, if the last byte of a print file is a Form Feed (optionally followed by a Carriage Return), then ignore it. FORCE, force the output file to end with a page up. The default is STANDARD. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: LASTFF=STRIP SPLARGS='' - When a virtual printer is allocated to a session, a CP SPOOL command is issued against it to point the output from the virtual printer to the proper destination. Normally, the following CP command will be used: 'SPOOL TO ', where is the virtual device address of the virtual printer allocated to the session, and is the userid specified on the DEST parameter. SPLARGS allows this default to be overridden with user specified SPOOL command arguments. If specified, then the given arguments will be appended to 'SPOOL ' to form the SPOOL command that will be used when the virtual printer is allocated to the session. The user is responsible for ensuring that this SPOOL command will get the output spool files to the proper destination. If the parameter's value is null, then the default SPOOL command will be used. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: SPLARGS='TO SYSTEM' TAGARGS='' - When a virtual printer is allocated to a session, a CP TAG command is issued against it to provide the destination with an indication as to where the output spool files should be routed to. Normally, the following CP command will be used: 'TAG DEV ', where is the virtual device address of the virtual printer allocated to the session, and is the name of the LU that the session belongs to. TAGARGS allows this default to be overridden with user specified TAG command arguments. If specified, then the given arguments will be appended to 'TAG DEV ' to form the TAG command that will be used when the virtual printer is allocated to the session. The user is responsible for ensuring that this TAG command will get the output spool files to the proper destination. If the parameter's value is null, then the default TAG command will be used. This parameter will be applied to all the LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: TAGARGS='LOCALPRT' CLSARGS=' - When a print file has been received on a session, a CP CLOSE command is issued against the virtual printer allocated to the session so that the output spool file containing the received data will be closed and sent to the destination. Normally, the following CP command will be used: 'CLOSE NAME OUTPUT', where is the virtual device address of the virtual printer allocated to the session, and is the name of the LU that the session belongs to. CLSARGS allows this default to be overridden with user specified CLOSE command arguments. If specified, then the given arguments will be appended to 'CLOSE ' to form the CLOSE command that will be used when the end of a print file is detected. The user is responsible for ensuring that this CLOSE command will get the output spool files to the proper destination. If the parameter's value is null, then the default CLOSE command will be used. This parameter will be applied to all LUs specified on the LUS and GENLUS parameters that follow this parameter. Example: CLSARGS='NAME UNKNOWN LISTING DIST NETWORK' TRACE=YES|NO - Enable or disable runtime tracing. The runtime tracing is very verbose and contains dumps of the input and output buffers and the VTAM RPLs. The default is to disable tracing. Example: TRACE=YES INDUMP=YES|NO - Enable or disable the dumping of the input buffers containing the data received from VTAM. The default is to disable input buffer dumping. Example: INDUMP=YES OUTDUMP=YES|NO - Enable or disable the dumping of the output buffers containing the data being written to the output spool files. The default is to disable output buffer dumping. Example: OUTDUMP=YES OUTSUP=YES|NO - Enable or disable the suppressing of the writes to the output spool files. If enabled, no output spool files will be created. The default is to disable output suppressing. Example: OUTSUP=YES It is important to note that most of the parameters affect the LUS and GENLUS statements that follow them, so you set any parameters before using the LUS or GENLUS parameter. Most of the parameter defaults can be used as-is, the only real required parameter (other than the LUS or GENLUS parameter) is the DEST parameter. It is admitted that this syntax is kind of painful, and it is hoped that a future version that uses a configuration file will be much more flexible (but you get what you pay for...). If you are looking for a vendor supported version of this code, please contact IBM or Interlink, both of whom have "ported" this code to the MVS environment (and neither of which, I believe, has a VM version). The VPS product also provides this capability (but was not derived from this code). Bruce Crabill BRUCE@UMDD.UMD.EDU