If a macro or copy member is not found in the list of paths specified in the Library Search Path, the assembler can invoke a program to retrieve the required file. Typically, this program will download the file from a mainframe library using a file transfer utility available on your workstation. The library exit program is specified using the LIBEXIT assembler option.
The string specified in the LIBEXIT option is used as a template for the command to be invoked as the library exit program. If there are no ampersands within the string, the command will be the string followed by a space character and the member name. Otherwise, the string should contain one or more pairs of &M, &m or &T characters. Each &M or &m will be replaced with the member name in upper or lower case respectively. Each &T will be replaced by a single letter indicating how the member was referenced: 'M' indicates the member is being referenced as a macro, 'C' indicates the member is being referenced in a COPY statement, and 'O' indicates that the member is being referenced by the O' attribute. In addition, && will be replaced by a single ampersand. After the substitutions are completed, the resulting string will be invoked as the library exit command. For example:
LIBEXIT("RECEIVE C:\MACROS\&M.MAC A:'SYS1.MACLIB(&M)'")
The example above will work within an option file. The same option on the Windows command line could be specified as follows:
"-le\"RECEIVE C:\MACROS\&M.MAC A:'SYS1.MACLIB(&M)'\""
The exit program may be written in any language available on your workstation, but is typically written in the command language, such as REXX or UNIX shell script. The exit program will be passed the name of the macro or copy member to be retrieved. The program should retrieve the file and put it into one of the directories specified in the Library Search Path. When the exit program receives control, the X390LIB environment variable will be set to the full Library Search Path. If successful, the program should exit with return code 0, or if unsuccessful it should exit with a non-zero code.
If the workstation is connected to the host mainframe via TCP/IP, the FTP command can be used to retrieve macros and copy members. If the connection is via one of the many 3270 emulation packages, the RECEIVE command is usually available to perform downloads. In simple cases, the FTP or RECEIVE command can be used directly as the library exit program. However, usually a script must be written to control the FTP or RECEIVE command.
Most of the time, the library exit program will need to determine which host library will be used as the source of the macro or copy member to be retrieved. In the case of using the RECEIVE command, the library exit program should probably ensure that the 3270 host session to be used is signed on to TSO, CMS, or CICS before the RECEIVE command is executed. This can be accomplished using the (Extended) High Level Language Application Programming Interface (E)HLLAPI available with most 3270 emulators.