LBSERV (Control IBM Tape Library) Macro

LBSERV allows passing tape handling requests to an IBM® Tape Library Dataserver.

These requests are passed in one of three ways:

  • directly via VSE Tape Library Support (TLS)
  • via the Library Control Device Driver (LCDD) in z/VSE®
  • via the VSE Guest Server (VGS) machine in VM (see DFSMS/VM Removable Media Services User's Guide and Reference)

For sample usage, see "Example for an LBSERV MOUNT Request" in the System Macros User's Guide.

Supported IBM tape libraries:
  • IBM TS3500 Tape Library
  • IBM TotalStorage™ 3494 Tape Library
  • IBM Virtualization Engine TS7700

  • IBM TS7680 ProtecTier Deduplication Gateway

See Administering and Planning for information about TLS and on configuring one of these options.
For any LBSERV request, you must use the IJJLBSER mapping macro. IJJLBSER must start on doubleword boundary. After each LBSERV request (except CANCEL and RECEIVE) a WAIT macro must be issued, if the return code from the LBSERV request in register 15 is zero. After the ECB is posted, an LBSERV RECEIVE request must be issued, which provides return and reason code information in the field indicated by SERVL.
Note: The program using the LBSERV macro must reserve GETVIS space. If the LBSERV macro is supported via the VSE Guest Server (VGS), you must provide at least 100 K permanent PFIX for each partition using VGS. The following example defines the 100 K permanent PFIX above the 16 MB line: 
// SETPFIX LIMIT=(,100K),PERM
// EXEC ...SIZE= must reserve GETVIS space

Table 1 lists the input and output parameters that are required for the various function operands.

Table 1. LBSERV: Operands by Function
  CUU ECB LIBNAME MEMNAME SERVL SRCCAT TGTCAT VOLSER WRITE
AQUERY   i(*) o   i o   i  
CANCEL         i        
CMOUNT i i i b   i i i b o i
COPYEX   i i b   i     i  
CQUERY   i i b   i i b      
DQUERY i i     i o   o  
EJECT   i i b   i     i  
IQUERY   i i b   i i b      
LQUERY   i i b   i        
MINVENT   i i b i i i b i    
MOUNT i i i b   i   i b i i
RECEIVE         i        
RELEASE i i     i        
SETVCAT   i i b b i i b i i  
SQUERY   i(*) i b o   i o   i   
  'i' = required input parameter
  'o' = required output parameter
  'b' = input parameter contents may be a blank value to indicate
        optional
  '*' = a free CUU is required for this request when running under
        VM (VGS)
Note: In order to get CUU for CMOUNT, DQUERY, and MOUNT, use the EXTRACT macro or the ASSGN command to assign the device.

The following requirements for the caller, register usage convention, input parameters, and return codes apply to all LBSERV functions.

Format

Read syntax diagramSkip visual syntax diagramnameLBSERV FUNC=AQUERYCANCELCMOUNTCOPYEXCQUERYDQUERYEJECTIQUERYLQUERYMOUNTRECEIVERELEASESETVCATSQUERYMINVENT,CUU=name1( r1),ECB=name2( r2),LIBNAME=name3( r3),MEMNAME=name4( r4),SERVL=name5( r5),SRCCAT=name6( r6),TGTCAT=name7( r7),VOLSER=name8( r8),WRITE=name9( r9)
Notes:

Requirements for the caller

AMODE:
24 or 31
RMODE:
ANY
ASC Mode:
Primary

Register usage convention

r(x)
For register notation R(x) any general register from 2 to 12 can be used
Registers 0, 1
Will be destroyed.
Register 13
Must point to a 72 byte save area.
Register 14
Return register.
Register 15
Branch register at input, return code from LBSERV macro call on output

Parameters

CUU = name1 | (r1)
Address of an area containing a 4–character device number to be used for this operation.
ECB = name2 | (r2)
Address of an area containing the ECB, which is posted when the request completes.
LIBNAME = name3 | (r3)
Address of an 8 character area containing the tape library name, or blanks to indicate the default library.
MEMNAME = name4 | (r4)
Address of an area containing an 8–character name of a z/VSE library member. This member contains the list of volumes to be managed by an MINVENT request.
SERVL = name5 | (r5)
Address of an area where the return information is stored when the request completes. This area must start on a doubleword boundary. The area is mapped by macro IJJLBSER. The area 's length, IJJLTLN, must be stored into field IJJLTLEN of IJJLBSER by the user. It is checked at LBSERV invocation if its size is as large as required. The first part up to label IJJLTRST is available to the user. The rest is reserved for system use only.
SRCCAT = name6 | (r6)
Address of a 10-character area where the tape volume's category (source category) is specified or is returned. A blank name (10 blank characters) indicates to ignore the source category.
Valid category names are:
  • INSERT
  • MANEJECT (not for VGS)
  • PRIVATE (not for VGS)
  • SCRATCH
  • SCRATCHnn, nn=00-31 for LCDD, nn=00-15 for VGS (mapped to n=0-F)
  • SCRATCHn, n=0-F VGS only
TGTCAT = name7 | (r7)
Address of a 10-character area containing the new category name (target category) for the volume to be used for this function. The target category is assigned to the volume. Valid category names are:
  • blank
  • PRIVATE
  • SCRATCH
  • SCRATCHnn, nn=00-31 for LCDD, nn=00-15 for VGS (mapped to n=0-F)
  • SCRATCHn, n=0-F VGS only
  • VOLspecific

A blank field (10 blank characters) as category name indicates that the parameter is to be ignored and the category left unchanged.

VOLSER = name8 | (r8)
Address of an area containing the 6-character volume serial number of the volume to be queried, mounted, or ejected.
WRITE = name9 | (r9)
Address of an area containing a 1-character read/write flag, where R means read-only and W means write. R is the default.

Return Codes in Register 15

x'0000'
Request passed successfully. After ECB was posted issue LBSERV RECEIVE and check return and reason code for this request.
x'0004'
Request passed, but warning condition. Check reason code.
x'0005' or >x'0005'
Request not successful. Check reason code.