User's Guide

Find the TAE library where a program resides

Function:

Given a program name and its suffix, this function will find the first TAE library where the program resides. It is useful for avoiding hard-coded directory or path names in procedure PDFs that call system-specific routines.

This function is a TAE programmer's tool. The User Notes give examples of how to use GETLIB in TAE procedures. The default values for the parameters assume that the programmer wishes to find the location of a system command, and wants a string returned that will execute that file.

Parameters:

PROGRAM

Program name. The name of the program to search for.

OUT

Output string. The name of the variable that is to receive the output from the program. This must be a TAE string variable.

SUFFIX(--)

Suffix name. The SUFFIX is appended to PROGRAM to form the host-specific filename to be searched for. A period should not be included. The default specifies that no suffix should be used.

OUTFORM(COM)

Output format. The format of the string that is returned to the calling procedure. The default specifies that the value will be in the form of a command string.

  = COM: Command string.  The output library name
         is formatted into a system command string
         so it can be run in the calling procedure.

  = LIB: Library name.  Only the name of the library
         where PROGRAM is found is returned to the 
         calling procedure. 

Examples:

1. LAS> getlib program=write_log out=library outform=lib

   The name of the TAE library where the program WRITE_LOG resides is returned in the local variable 'library'.

2. LAS> getlib program=test out=hostcall

   Since OUTFORM is defaulted, the return value will be formatted into a string that will run the host system command. This command string is returned in the local variable 'hostcall'.

Description/Algorithm:

The libraries $USERLIB and $APLIB are searched one element at a time for the filename specified in PROGRAM and SUFFIX. Once found, the library name is returned in the local variable specified in OUT. If OUTFORM=COM, the return value is formatted so that it may be run from the calling procedure.

Nonfatal Error Messages:

None.

Fatal Error Messages:

1. [getlib-fatal] Fatal error encountered

   A fatal error was encountered. The message displayed prior to this one is the specific error that was encountered. Processing is terminated.

2. [getlib-lib] Error returning library

   An error was encountered returning the library to the TAE variable specified in OUT. Contact the system administrator.

3. [getlib-nolib] Library not found for <xxxxx>

   <xxxxx> could not be found in any of the libraries specified by $USERLIB or $APLIB. Ensure PROGRAM and SUFFIX where specified correctly.

User Notes:

1. The GETLIB program returns the name of the library where the specified program is first found.