5 HSC Stand-Alone Utilities

This chapter describes HSC stand-alone utilities. These utilities run as independent programs.

The following utilities are included:

Utility Administrator (SLUADMIN)
SLICREAT
Scratch Conversion Utility (SLUCONDB)

Utility Administrator (SLUADMIN)

The SLUADMIN program operates as a batch job and controls initialization processing for most utility functions. The utility administrator (SLUADMIN) can accept multiple commands which are handled as serial requests for multiple utilities. If all requirements needed to execute the utility function are met, control is passed to the appropriate program which handles the actual processing.

Utility functions represented by additional control statements are not started until the prior utility function stops and control is returned to the SLUADMIN program.

Caution:

The maximum length of a control statement is 32,767 characters. Exceeding this limit causes message SLS0241I to be displayed, which indicates an invalid utility control statement.

Invoking SLUADMIN

For convenience, most utility programs are packaged to appear as a single, user-invoked program. An exception is Scratch Conversion. All other utility functions are invoked as a normal batch job using the SLUADMIN program and user-specified commands needed to invoke the required utility function.

Utility functions represented by additional commands are not started until the prior utility function stops and control is returned to the SLUADMIN program.

The following is a generic example of JCL that can be modified to execute SLUADMIN. Where &rsquor;&rsquor;utility and CSV commands'' appears in this sample JCL, enter the utility or CSV commands you wish to execute.

For example:

SET HOSTID(HSC2) FORHOST(HSCB)
OFFLoad LOGF
SCREdist ACS(01)

The following example shows JCL that invokes SLUADMIN:

Example 5-1 JCL to Invoke SLUADMIN

//jobname    job (account),programmer,REGION=0M
//S1 EXEC    PGM=SLUADMIN,PARM=MIXED
//STEPLIB    DD DSN=your.sea.linklib,DISP=SHR
//SLSPRINT   DD SYSOUT=A
//SLSIN DD   *
  utility and CSV commands
          .
          .
          .
//**************************************************************
//* Optional UUI Output Definition Statements *
//**************************************************************
//SLSCSV  DD DSN=yourcsv.output.dataset,DISP=SHR
//SLSCSVX DD SYSOUT=*
//SLSXML  DD DSN=yourxml.output.dataset,DISP=SHR
/*
//

Note:

Specify a region size of 0M on the JOB statement for all utility functions.

SLUADMIN Execution Parameters

The following optional parameters may be specified for PARM= on the SLUADMIN EXEC statement:

NOHDR: Suppresses printing of report headings. This parameter only affects programs that produce report output., such as ACTIvities, VOLRpt, and VTVRpt, etc.

Note:

NOHDR and LINECNT are mutually exclusive.

If NOHDR is not specified, the default is to print headings that include the following information:

date/time of the report
page numbers
host software version number
name of the utility function executed

NOPHDR

Suppresses printing of page headings, but produces control headers in the output, such as:

SLS0030I Message ID NNNN Help Info:

SLS0041I Command CCCCCCCC Help Info:

Note:

NOPHDR is mutually exclusive with LINECNT and NOHDR.

This parameter is useful when you issue the Display CMd or Display Message command to create a file that includes help text for commands or messages.

MIXED

Prints all report headings and messages in mixed case. The default is uppercase.

LINECNT=nn

Specifies the number of lines per page for the SLUADMIN report. Allowable values are 10 through 99; the default is 60 lines per page.

Note:

LINECNT and NOHDR are mutually exclusive.

SSYS(ssss)

Optionally, specifies the name of the HSC subsystem for which the SLUADMIN utility is being run. This parameter is required when the HSC subsystem(s) running on the LPAR have specified the MULT parameter.

XMLDate(date)

Specifies the format of date fields in XML and CSV output. Valid date formats include the following:

yyyymondd
yyyy-mm-dd
yyyy-mon-dd
HEXSTCK (hex character STCK format)

The default format is yyyymondd. For example, 2005Oct14.

XMLCase(case)

Specifies the case of alphabetic data fields in XML and CSV output. Valid case formats include the following:

M indicates mixed uppercase and lowercase. This is the default.
U indicates uppercase

SLUADMIN Definition Statements

Additional statements may be required for certain HSC and VTCS commands. In this publication, these statements are described with the applicable command.

General Definition Statements

The following definition statements are always required:

STEPLIB

specifies the link library that contains the ELS modules.
SLSPRINT

specifies the destination for the utility output (plain text).
SLSIN

specifies the input to the SLUADMIN (utility command names and parameters).

Note:
SLSIN can also include the SDD command, See "SDD Command" for more information.
SLSOUT

specifies the destination for SLUADMIN processing messages.

CDS Definition Statements

One or more of the following CDS definition statements are required for utility commands executed on a host where the HSC is inactive. These statements specify a primary CDS, and optionally, a secondary and standby CDS.

Note:

These statements can be omitted for commands that execute on a host with HSC active. If these statements are omitted, the data sets used by the active HSC on the host are accessed.

SLSCNTL

specifies the primary CDS. This statement is required for utility commands executed on a host where the HSC is inactive.

SLSCNTL2

optionally, specifies the secondary CDS.

If a secondary CDS exists, include this statement so that if a switch occurs and the secondary CDS becomes active, the CDSs can be reordered to maintain database integrity.

SLSSTBY

optionally, specifies the standby CDS.

If a standby CDS exists, include this statement so that if a switch occurs and the standby CDS becomes active, the CDSs can be reordered to maintain database integrity.

When you specify CDS definition statements, the following conditions apply:

The number of DD statements specified must equal the number defined by the SET TCHNIQE command. When you run the SET TCHNIQE command, the number of DD statements defined must equal the number implied by the new technique.
Rules for selecting primary, secondary, and standby CDS versions are the same as those used by the HSC subsystem. Refer to the publication Managing HSC and VTCS for more information about CDS configuration.
For utilities that are "read only" (for example, VOLRpt), you can specify a single DD (SLSCNTL) and no internal or external name validation is performed.

UUI Output Definition Statements

One or more of the following definition statements are required when you wish to generate output types added through Unified User Interface (UUI) requests. See "Requesting SLUADMIN Output" for more information about requesting these output types.

SLSCSV: specifies the destination for the utility output in Comma Separated Value (CSV) format.
SLSCSVX: specifies the destination for CSV exceptions.
SLSXML: specifies the destination for the utility output in structured XML format.

Requesting SLUADMIN Output

In addition to plain text, SLUADMIN supports output types added through Unified User Interface (UUI) requests. Refer to the ELS Programming Reference for a list of commands and utilities supported by the UUI.

The output type is controlled by DD statements defined in the SLUADMIN JCL. Output types include the following:

Plain text

Plain text output is always produced and is unchanged from previous releases. Output is written to the data set specified by the SLSPRINT definition statement.
Structured XML

This output type is optional and is generated only if the SLSXML definition statement is specified. Output is written to the data set specified by this statement.

Structured XML is a well-formed XML data stream containing XML header tags, data tags, and data element content. Refer to the ELS Programming Reference for XML tag names and structure for all UUI requests.
Comma Separated Values (CSV)

This output type is optional and is generated only if the CSV command and SLSCSV definition statement are specified.

CSV output can be customized. A template of XML data tag names can be input by the user to specify which data values will be output. The output data is a single CSV header line followed by CSV detail lines.

A CSV header line is a list of the XML data tag names requested; each name is separated by a comma. Each CSV detail line is a specified fixed number of data values, separated by a comma. This kind of output is readily adaptable as input into spreadsheets or customizable report writers.

Requesting XML Output

If the SLSXML DD statement is present, it indicates that structured XML output should be provided for all SLUADMIN commands that support the UUI interface.

When XML is generated, exceptions are generated under their own header tag, <exceptions>, at the end of each request. Each exception is reported using the <reason> tag. Refer to the ELS Programming Reference for more information.

Requesting CSV Output

If the SLSCSV DD statement is present, comma separated value (CSV) output is provided for all SLUADMIN commands that support the UUI interface.

If the SLSCSVX DD statement is present, CSV exceptions are reported. The SLSCSVX DD statement is valid only if the SLSCSV DD statement is provided. CSV exceptions are generated only if the CSV command is in effect for a request.

The default DCB information for this DD is the same as SLSPRINT, LRECL=121, RECFM=FB).

CSV Command

The CSV command controls CSV output processing.

Each CSV command contains a list of CSV element definitions separated by commas. Each CSV element definition specifies an XML data tag name with optional XML structure tag and subscript values. Refer to the ELS Programming Reference for more information about ELS XML tags.

Syntax:

Figure 5-1 CSV command syntax

Parameters:

OFF

Disables CSV processing for subsequent requests.

Note:

OFF is mutually exclusive with all other CSV parameters.

FIeld

Required if OFF is not specified.

nnnn- is an optional field name prefix containing 1 to 4 numeric characters followed by a dash. When a field name is prefixed by "n(nnn)-", the CSV output for the field always contains exactly the number of characters specified. Numeric fields are right-justified with the most left-most digits truncated; other fields are left-justified with the right-most characters truncated. If the value specified is longer than the actual value, it is padded with blanks on the left for numeric fields and blanks on the right for other fields.

For example:

8-acs_status truncates the acs_status value to 8 characters.

12-acs_status blank-pads the acs_status value to 12 characters.

The maximum value of nnnn is 1024. The specification of "nnnn-" is valid only when the parameter FIXed is also specified.
structuretag(nnn).datatag is an optional XML structure tag and data tag pair. An XML structure tag is an element that contains other elements but does not have content value. Refer to the ELS Programming Reference for more information about ELS XML tags.

Specify an XML structure tag/data tag pair only when the data tag occurs within multiple structure tags. For example, the DISPLAY LSM request data tag free_cell_count is used under the structure lsm_data to contain the total LSM free cell count and under the structure panel_data to contain the panel free cell count. Specifying lsm_data.free_cell_count requests the free cell count from the lsm_data structure; specifying panel_data.free_cell_count requests the free cell count from the panel_data structure. If no structure tag is coded for a data tag that occurs under multiple structure tags, the first occurrence of the data tag in the generated XML is used.

nnn is an optional subscript that determines how many of the multiple XML data values are included in the CSV output.

Specify a subscript only when the structured XML data for a single request contains multiple XML structure elements with the same name. This is indicated in the requestXML description whenever the column labelled "Maximum Occurrences" is greater than 1. A subscript value can be specified in BOTH the structure tag name AND the data tag name, for example:
```
CSV FIELD=(mvc_instance(4).volser,+
mvc_instance(4).partition_id(2))
```
creates CSV output with 12 fields, four mvc_instance volser occurrences, followed by two fields representing the partition_id values associated with the first MVC volser, then two fields representing the partition_id values associated with the second MVC, etc.
datatag(nnn) is an optional XML data tag. If a data tag does not under more than one structure tag in a request, it is not necessary to specify a structure tag qualifier.

nnn is an optional subscript that determines how many of the multiple XML data values are included in the CSV output.

Specify a subscript only when the structured XML data for a single request contains multiple XML structure elements with the same name. This is indicated in the requestXML description whenever the column labelled "Maximum Occurrences" is greater than 1.

Note:
The XML tag names are NOT case-sensitive and can be specified in any combination of upper and lower case characters.

BReak

Required if OFF is not specified. The break tag must be a valid structure tag defined for the input request. Whenever a trailer tag matching the break tag is found in the output process, a new CSV record is created. Examples of valid break tags are:

For DISPLAY CDS, cds_data or host_data
For VOLRPT or Display Volume, volume_data

FIxed

Generates fixed format CSV output. Each field in the CSV output is blank-padded so that it occupies a fixed number of characters. This option can be used to create a customer-specified format flat file for reporting.

NOTITLe

Specifies that no CSV title line is produced. If this keyword is omitted, the first line of each CSV request is a title line containing comma separated tag names.

TITLe

If TITLe is specified, the title names specified are used in the title output line in place of the XML tag names. For any omitted title name, the specified XML tag name from the FIELD parameter is used in the title.

The following SLUADMIN JCL executes the MVCRPt command to produce a report of the percentage of space available for all MVCs in CSV format. After the job executes, you can FTP the CSV output file to your spreadsheet application.

Refer to the ELS Programming Reference for information about the structure and data tags used in this example.

Example 5-2 CSV Output for the MVCRPT command

//MVCREPT JOB x,CHRIS,CLASS=A,MSGCLASS=E
//*
//*
//*
//MVCRPT EXEC PGM=SLUADMIN,
// PARM='MIXED,XMLDATE=YYYY-MM-DD'
//STEPLIB DD DSN=your.sea.LINKLIB,DISP=SHR
//SLSCNTL DD DSN=your.sea.CLUSTER.CDS,DISP=SHR
//SLSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SLSCSV DD DISP=(,CATLG),DSN=hlq.MVCREPT.CSV,
// DCB=(RECFM=VB,LRECL=4096,BLKSIZE=32000),
// UNIT=SYSDA,SPACE=(CYL,(x,y))
//SLSIN DD *
CSV FIELD=(mvc_data.volser,mvc_data.percent_available)+
BREAK=(mvc_data)+
NOTITLE
MVCRPT
/* //*
//

SLUADMIN Program Return Codes

The SLUADMIN program sets a return code for the execution of the job step as described below.

The return code for each utility function is listed in a message. For return codes other than 0, additional messages are listed providing more information and description of the error condition. Refer to the publication ELS Messages and Codes for any messages encountered.

The SLUADMIN utility includes the following return codes:

0 indicates that all utility functions requested via control statements completed normally.
4 indicates that at least one utility function encountered an abnormal situation, but it did not cause termination of that utility function or any subsequent utility functions.
8 indicates that at least one utility function encountered an error condition that prevented continuation of that utility function, but any subsequent utility functions represented by control statements were attempted.
12 indicates that an error condition was detected that either prevented the start of any utility functions, or terminated the active utility function and prevented processing of subsequent utility functions.

Note:

If the return code occurred because of a problem with the HSC CDS, the problem must be resolved before the HSC can be initialized safely.

Reports Created by Utility Commands

Several utility commands produce reports when executed. These reports are in addition to the utility function. The following utility commands produce reports:

LIBGen
ACTIvities
AUDit
BACKup
MOVe
VOLRpt

Report Headings

Report headings include the following information:

date/time of the report
page number(s)
host software version number
name of the utility function executed

SLICREAT

The SLICREAT program creates library control data sets and displays library volume capacity in a confirmation message.

These library control data sets are created based on the data set definitions you specify in the SLICREAT data set initialization JCL.

Using SLICREAT involves the following steps:

Create data set definitions in the data set initialization JCL using the SLICREAT program.
Execute the SLICREAT program to create the library control data sets.
Verify successful completion of the SLICREAT program and note the library volume capacity displayed in the confirming message.

These steps are described in the following sections. They must be performed before the library is operational.

Note:

Before using SLICREAT, you must first create, assemble and link the LIBGen macros. Refer to the publication Configuring HSC and VTCS for more information.
You can use SLICREAT to reformat your HSC SLSJRNnn journal file(s). Refer to the ELS Legacy Interfaces Reference for more information.

Creating Control Data Set Initialization JCL

Creating the definitions for the library control data set is done by coding JCL in a job file named SLICREAT.

The following is an example of JCL for the SLICREAT program. This sample is also included in the HSC SAMPLIB as member JCLCRT.

Example 5-3 SLICREAT JCL

//SLICREAT JOB (account),'programmer',CLASS=A
//CREATE   EXEC PGM=SLICREAT,                    CDS CREATE MODULE 
//              PARM='libgen-load-module-name', 
//              REGION=0M 
//* 
//STEPLIB  DD   DSN=your.sea.linklib,DISP=SHR 
//SYSPRINT DD   SYSOUT=*                         MESSAGES 
//* 
//****************************************************************** 
//*             LIBRARY PRIMARY CONTROL DATASET (CDS) //****************************************************************** 
//SLSCNTL  DD   DSN=SLS.SLSCNTL, P               RIMARY CDS 
//              SPACE=(4096,s,,CONTIG,ROUND),    REPLACE 's' WITH YOUR 
//              DISP=(NEW,CATLG,DELETE),         SPACE CALCULATIONS 
//              UNIT=SYSDA 
//****************************************************************** 
//*             LIBRARY SECONDARY CONTROL DATASET (CDS) //****************************************************************** 
//SLSCNTL2 DD   DSN=SLS.SLSCNTL2,                SECONDARY CDS 
//              SPACE=(4096,s,,CONTIG,ROUND),    REPLACE 's' WITH YOUR 
//              DISP=(NEW,CATLG,DELETE),         SPACE CALCULATIONS 
//              UNIT=SYSDA 
//****************************************************************** 
//*             LIBRARY STANDBY CONTROL DATASET (CDS) //****************************************************************** /
/SLSSTBY DD     DSN=SLS.SLSCNTL3,                STANDBY CDS 
//              SPACE=(4096,s,,CONTIG,ROUND),    REPLACE 's' WITH YOUR 
//              DISP=(NEW,CATLG,DELETE),         SPACE CALCULATIONS 
//              UNIT=SYSDA 
//****************************************************************** 
//*             LIBRARY JOURNAL DATASET (INITIAL) //****************************************************************** 
//SLSJRN01 DD   DSN=SLS.SLSJRN01,                INITIAL JOURNAL 
//              SPACE=(4096,u,,CONTIG,ROUND),    REPLACE 'u' WITH YOUR 
//              DISP=(NEW,CATLG,DELETE),         SPACE CALCULATIONS 
//              UNIT=SYSDA 
//****************************************************************** /
/*              LIBRARY JOURNAL DATASET (ALTERNATE) //****************************************************************** 
//SLSJRN02 DD   DSN=SLS.SLSJRN02,                ALTERNATE JOURNAL 
//              SPACE=(4096,u,,CONTIG,ROUND),    REPLACE 'u' WITH YOUR 
//              DISP=(NEW,CATLG,DELETE),         SPACE CALCULATIONS 
//              UNIT=SYSDA 
//****************************************************************** 
//*             ONE PAIR OF JOURNALS ARE REQUIRED FOR EACH GENED HOST //****************************************************************** 
//*

DD Statements

The following JCL DD statements must be used to define the library control data sets:

SYSPRINT

output messages.

Refer to the following criteria when allocating the control data sets:

Do not specify the DCB statement. The HSC defines the required block size (4K).
The data set(s) must be allocated in a single contiguous extent.
The CDS(s) must not include existing data sets containing records prior to running the SLICREAT process.
Oracle StorageTek recommends that the CDSs do not reside on the same volume(s) as other CDSs or other data sets that generate high I/O activity.

SLSCNTL

primary library control data set.

This is the initial data set that is used to control and synchronize all activities within the HSC. It is used by the HSC until the controlling data set is switched to the secondary, either automatically or manually.

SLSCNTL also controls the SLICREAT process. If you do not include an SLSCNTL DD statement when you run SLICREAT, as follows:

the CDSs will not be formatted, and
the size requirement (in blocks) of the LIBGEN load module included in the PARM statement will be calculated and reported and journal formatting will be attempted.

SLSCNTL2

secondary copy of the primary control data set.

This is required only if the SLIRCVRY macro TCHNIQE parameter is SHADOW, STANDBY, BOTH, or ALL.

SLSSTBY

standby control data set.

This data set is required only if the SLIRCVRY macro TCHNIQE parameter is STANDBY or ALL. A secondary data set is required if a standby control data set is specified. This data set is also required for STBYONLY processing (see "Using SLICREAT to Create Only the Standby CDS").

Executing the SLICREAT Program

Execute the SLICREAT program to create the library control data sets.

SLICREAT EXEC Statement

Use the following EXEC statement to execute the SLICREAT program:

EXEC PGM=SLICREAT,PARM=' libgen-load-module-name '

The PARM= value indicates the LIBGEN load module name. The STEPLIB statement must point to the appropriate library in which the LIBGEN load module currently resides.

Note:

SLICREAT requires a LIBGEN load module assembled with the same level macros as the release LINKLIB. A LIBGEN load module created with earlier HSC releases cannot be used as input to a later release of SLICREAT.
The CDS files that are created by SLICREAT (SLSCNTL, SLSCNTL2, and SLSSTBY) are verified to be empty data sets prior to being formatted. If SLICREAT identifies any of these files as containing records, an error message is displayed and the creation process terminates. If this occurs, specify a different data set(s) or delete and redefine the data set(s) and re-execute SLICREAT.

Verifying Successful Completion of the SLICREAT Program

After the SLICREAT program is successfully processed, a message is generated indicating the status and the capacity of the library. An example is:

SLS0557I DATABASE SUCCESSFULLY INITIALIZED; TOTAL CARTRIDGECAPACITY: DDDDDDDDDDDD VOLUMES

Calculating Cartridge Capacity - SL8500 and SL3000

Message SLS0557I displays the total cartridge capacity for the library. For the SL8500 and SL3000 libraries, you must first vary the library online (Vary ACS command) to see the actual capacity of the library rather than the maximum capacity of the library. Before you vary the library, the maximum capacity is based on the highest possible number of panels that the HSC allows to be defined, not the number you defined in LIBGEN.

After you vary the library online, issue the Display Acs or Display Lsm command to show the actual library capacity.

Using SLICREAT to Create Only the Standby CDS

SLICREAT can be used to create an additional CDS. If the HSC was previously installed without a standby CDS, you can run the SLICREAT program to create one.

This method does not make a backup of the primary CDS. It formats the additional CDS and enables you to activate it with the CDS Enable command.

SLICREAT EXEC Statement to Create Standby CDS

Specify PARM='STBYONLY' on the SLICREAT EXEC statement to create a standby CDS:

EXEC PGM=SLICREAT,PARM='STBYONLY'

Note:

You must have a primary CDS before you can run the STBYONLY option of SLICREAT.
For a standby data set to be recognized by the system, it must be defined by a CDSDEF statement in the PARMLIB.

Using SLICREAT to Calculate DASD Space

You can determine the minimum DASD space required for the CDSs by executing SLICREAT without specifying the SLSCNTL and SLSJRNnn DD statements. The HSC generates a message that indicates the minimum space requirements in 4096-byte blocks. When you execute SLICREAT, you must specify the number of blocks for each of these data sets that is at least as large as this minimum.

Note:

If you are specifying multiple CDSs (SLSCNTL2, SLSSTBY), Oracle StorageTek recommends that you allocate the same amount of space (in blocks) for all your data sets when you define them.

If the data sets are defined with different space allocations, the HSC uses the size of the smallest data set to determine the number of 4K blocks that it will use for the CDS. The additional space in the other CDS data sets, if any, will not be used by the HSC.

The difference in space between the minimum space required (returned by SLICREAT) and the size of the smallest CDS copy is formatted as CDS free blocks.

Scratch Conversion Utility (SLUCONDB)

The SLUCONDB program generates scratch transactions from CA-1, CA-DYNAM/TLMS, DFSMSrmm and Zara tape management systems, or from a file extracted from a client system by the SMC SMCUDBX utility.

Note:

See "Tape Management Extract Utility (SMCUDBX)" for more information about the SMCUDBX utility

SLUCONDB can execute as a standalone utility, generating scratch transactions for input to SLUADMIN. Alternatively, it can execute on a host with an active HSC system, and, using the SLUCONDB LIBONLY parameter, generate UUI scratch transactions sent directly to the active HSC system. In a client/server system, using the TAPEPLEX parameter, SLUCONDB can access an HSC system on another host to acquire CDS data and to send UUI scratch transactions.

WARNING:

SLUCONDB should not be executed with any other SCRAtch, UNSCratch, or REPLaceall activity.
The SLUCONDB module is no longer distributed as source. If you wish to synchronize scratch processing with a tape management system not supported by SLUCONDB, alter one of the distributed SLUCONDB tape management interface modules to use the SLUDRINF interface format.

Input Formats

SLUCONDB uses program parameters to determine the Tape Management System interface (SLUDR*) routine to invoke. See Appendix C, "Tape Management System Interface (SLUDR*) Routines" for more information about these routines.

You can supply SLUCONDB input values using the PARM parameter on the JCL EXEC statement when running the SLUCONDB utility. You can use either the following formats:

Keyword Format
Positional Format

Consider the following:

The GRACE parameter is only permitted using the keyword format.
The LIBONLY parameter is only permitted using the positional format.

Keyword Format

The following section describes the syntax and parameters for keyword format of the PARM parameter.

Syntax

Figure 5-2 SLUCONDB PARM parameter syntax (keyword format)

Parameters

If you use the keyword format, adhere to the following syntax rules:

Keywords and values must be separated by "=" (except for the MIXED keyword, which does not have a value).
Extraneous commas between keywords are not allowed. For example, the following is invalid: PARM='TMC=TMS,,MIXED'.
Duplicate keywords are not allowed.

Valid parameters include the following:

PARM=

specifies that the parameters that follow can be accessed by the program indicated in the PGM parameter in the JCL.

The defaults for the PARM are:

TMS
All label types
Scratch eligibility begins on January 1, 1900 and ends on the current system date
Uppercase only
Generate scratch transactions (no direct update).

TMC=

optionally, specifies the tape management system. For example:

TMS specifies the CA-1 tape management system (TMS). This is the default.
TLMS optionally, specifies the TLMS: CA-DYNAM/TLMS tape management system.
RMM optionally, specifies the DFSMSrmm tape management system.
SMC optionally, specifies the extract file from the SMC utility SMCUDBX.

If SMC is specified, label and date parameters are not permitted. (Label and date selection are performed by the SMC utility when it creates the extract file.)
ZARA optionally, specifies the ZARA tape management system.

subsystem-name is an optional subsystem name.

SCRPOOL=

optionally, specifies the scratch pool label type used by the library. Valid label type values are:

(SL) indicates standard label (the default).
(NL) indicates non-labeled.
(NSL) indicates non-standard label.
(AL) indicates ANSI label.
(SUL) indicates standard user label

DATE=

optionally, specifies the date or date range when a volume became scratch in the TMC.

1900001 optionally, specifies January 1, 1900 as the date. This is the default.
TODAY optionally, indicates the current system date. Only volumes placed in scratch status on this date are processed.
yyyyddd1 optionally, the "from" date. The "to" date defaults to the current system date. All specified dates are in Julian notation.

All volumes placed in scratch status starting on day yyyyddd1 through today's date are processed.
yyyyddd1-yyyyddd2 optionally, the date range in which the volumes became scratch. Neither of these dates can be greater than the current system date.

All volumes placed in scratch status starting on day yyyyddd1 through day yyyyddd2 are processed.

MIXED

optionally, specifies to print all the headings and messages in mixed case characters (uppercase and lowercase characters).

Note:

If a comma is specified, or if this keyword is not specified, the system defaults to uppercase letters.

TAPEPLEX=

optionally, specifies the name of an SMC TapePlex to be used to extract CDS volumes and run UUI scratch commands.

tttttttt is the TapePlex name.

The specified TapePlex may be a local HSC executing on the same host as SLUCONDB, or may be an HSC subsystem on another host accessed via the SMC client server feature. Specifying the TAPEPLEX parameter requires an active SMC system on the SLUCONDB host, an active HSC system for the TapePlex, and requires that SLUCONDB be executed from an APF-authorized library.

GRACE=

optionally, specifies a grace period (in hours) for scratch eligibility. A volume accessed after the start of the SLUCONDB run, minus the grace period, is not eligible for scratch.

nnn is a 1-3 digit numeric value from 0 to 999, representing the grace period in hours.

Positional Format

The following section describes the syntax and parameters for positional format of the PARM parameter.

Syntax

Note:

You must enter parameters in the specified order and include commas for omitted parameters.

Figure 5-3 SLUCONDB PARM parameter syntax (positional format)

Parameters

PARM=

specifies that the parameters that follow can be accessed by the program indicated in the PGM parameter in the JCL.

The defaults for the PARM are:

TMS
All label types
Scratch eligibility begins on January 1, 1900 and ends on the current system date
Uppercase only
Generate scratch transactions (no direct update).

The keywords for the PARM are positional. If you accept the system defaults, either do not specify PARM, or code ”PARM=”.

TMS

optionally, specifies the CA-1 tape management system (TMS). This is the default.

TLMS

optionally, specifies the TLMS: CA-DYNAM/TLMS tape management system.

RMM

optionally, specifies the DFSMSrmm tape management system.

ZARA

optionally, specifies the ZARA tape management system.

SMC

optionally, specifies the extract file from the SMC utility SMCUDBX.

If SMC is specified, label and date parameters are not permitted. (Label and date selection are performed by the SMC utility when it creates the extract file.)

SCRPOOL

optionally, specifies the scratch pool label type used by the library. Valid label type values are:

(SL) indicates standard label (the default).
(NL) indicates non-labeled.
(NSL) indicates non-standard label.
(AL) indicates ANSI label.
(SUL) indicates standard user label

Date Related Parameters

The following date-related parameters specify the date or date range when a volume became scratch in the TMC.

1900001

optionally, specifies January 1, 1900 as the date. This is the default.

TODAY

optionally, indicates the current system date. Only volumes placed in scratch status on this date are processed.

yyyyddd1

optionally, the "from" date. The "to" date defaults to the current system date. All specified dates are in Julian notation.

All volumes placed in scratch status starting on day yyyyddd1 through today's date are processed.

yyyyddd1-yyyyddd2

optionally, the date range in which the volumes became scratch. Neither of these dates can be greater than the current system date.

All volumes placed in scratch status starting on day yyyyddd1 through day yyyyddd2 are processed.

MIXED

optionally, specifies to print all the headings and messages in mixed case characters (uppercase and lowercase characters).

Note:

If a comma is specified, or if this keyword is not specified, the system defaults to uppercase letters.

LIBONLY

optionally, specifies that volumes are to be placed in scratch status through the UUI interface. Specifying LIBONLY requires an active HSC, and requires that SLUCONDB be executed from an APF-authorized library

TAPEPLEX

optionally, specifies the name of an SMC tapeplex to be used to extract CDS volumes and run UUI scratch commands.

tttttttt is the TapePlex name.

JCL Requirements

The following definitions apply to the SLUCONDB JCL:

SLSTMS

input to the utility in the form of either the CA-1 TMC, CA-DYNAM/TLMS Volume Master File (VMF), or DFSMSrmm report extract file. This statement is required.

SLSSOUT

output from the utility specifying the Scratch Update utility control statement. This statement is required if LIBONLY or TAPEPLEX is not specified.

If specifying a temporary or permanent data set for 'DSN=' in the JCL, you must include the appropriate DCB information (that is, LRECL=72).

SLSPRINT

output messages from the utility program. This statement is required.

Note:

The Scratch Conversion utility uses the UUI to extract volume and VTV records from the CDS. The UUI requires read access to the CDS, either from statements in the JCL or by getting the data set information from an active HSC. The SLSCNTL, SLSCNTL2, and SLSSTBY DD statements are optional if an active HSC is running on the same system. The SLSCNTL, SLSCNTL2, and SLSSTBY DD statements are not allowed if either LIBONLY or TAPEPLEX parameters are specified.

SLSCNTL

the primary control data set. This statement is optional.

SLSCNTL2

the secondary control data set. This statement is optional.

SLSSTBY

the standby control data set. This statement is optional.

JCL Examples

The following examples illustrate both generating scratch transactions and directly updating the HSC CDS.

The library referred to as "your.sea.smp/e.loadlib" in the following examples refers to the SEALINK library generated during the ELS installation. This library contains the TMS interface (SLUDR*) modules. If you reassemble these modules, this library is the output of your link edit.

Note:

The UNIT, SPACE, and DCB parameter settings are determined by the user.

Example 1

The following is an example of SLUCONDB JCL to process the tape management databases, with active HSC, generating scratch update transactions:

//JOBSCUP JOB (account),programmer
//STEP1     EXEC PGM=SLUCONDB,
//               PARM=('TLMS,,,MIXED')
//STEPLIB   DD DISP=SHR,DSN=your.sea.smp/e.loadlib
//SLSTMS    DD DSN=TMS.MASTER.FILE,DISP=SHR
//SLSSOUT   DD DSN=&&SCUPINPT,DISP=(NEW,PASS),
//          UNIT=,SPACE=,DCB=
//SLSPRINT  DD SYSOUT=*
//*
//STEP2     EXEC PGM=SLUADMIN,COND=(4,LT,STEP1),PARM=MIXED
//SLSIN     DD DSN=&&SCUPINPT,DISP=(OLD,DELETE)
//SLSPRINT  DD SYSOUT=*
//

Example 2

The following is an example of SLUCONDB JCL to process the TMS database, with HSC CDS DD names, generating scratch update transactions:

//JOBSCUP JOB (account),programmer
//STEP1     EXEC PGM=SLUCONDB,
//               PARM=(',,2009100-2009110,MIXED')
//STEPLIB   DD DISP=SHR,DSN=your.sea.smp/e.loadlib
//SLSTMS    DD DSN=TMS.MASTER.FILE,DISP=SHR
//SLSSOUT   DD DSN=&&SCUPINPT,DISP=(NEW,PASS),
//          UNIT=,SPACE=,DCB=
//SLSPRINT  DD SYSOUT=*
//SLSCNTL   DD DSN=primary.control.dataset,DISP=SHR
//SLSCNTL2  DD DSN=secondary.control.dataset,DISP=SHR
//SLSSTBY   DD DSN=standby.control.dataset,DISP=SHR
//*
//STEP2     EXEC PGM=SLUADMIN,COND=(4,LT,STEP1),PARM=MIXED
//SLSIN     DD DSN=&&SCUPINPT,DISP=(OLD,DELETE)
//SLSPRINT  DD SYSOUT=A
//

Example 3

The following is an example of SLUCONDB JCL to process the DFSMSrmm database, with direct scratch updates (HSC active on host):

//JOBSCUP JOB (account),programmer//STEP1     EXEC PGM=EDGHSKP,PARM='RPTEXT,DATEFORM(J)'//MESSAGE   DD DSN=rmm.message.dataset,DISP=SHR//REPTEXT   DD DSN=rmm.report.extract,DISP=SHR//*//STEP2     EXEC PGM=SLUCONDB,//               PARM=('RMM,,,MIXED,LIBONLY')//STEPLIB   DD DISP=SHR,DSN=your.sea.smp/e.loadlib//SLSTMS    DD DSN=rmm.report.extract,DISP=SHR//SLSPRINT  DD SYSOUT=*//

Example 4

The following is an example of SLUCONDB JCL to process the SMC extract file:

//JOBSCUP JOB (account),programmer//STEP1     EXEC PGM=SLUCONDB,PARM='SMC,,,MIXED,LIBONLY'//STEPLIB   DD DISP=SHR,DSN=your.sea.smp/e.loadlib//SLSTMS    DD DISP=SHR,DSN=your.smc.extract.file//SLSPRINT  DD SYSOUT=*//

Example 5

The following is an example of SLUCONDB JCL to process from SMC to a remote TapePlex:

//JOBSCUP JOB (account),programmer//STEP1     EXEC PGM=SLUCONDB,//               PARM=',,,MIXED,TAPEPLEX(PRODPLX)'//STEPLIB   DD DISP=SHR,DSN=your.sea.smp/e.loadlib//SLSTMS    DD DSN=TMS.MASTER.FILE,DISP=SHR//SLSPRINT  DD SYSOUT=*//

Output Description

SLUCONDB output includes the following:

a listing of input commands with appropriate messages if syntax errors occur
messages associated with errors in the SLUCONDB process
messages associated with error conditions resulting from an unsuccessful attempt to scratch a volume (using LIBONLY or TAPEPLEX parameters)
scratch input transactions (if LIBONLY or TAPEPLEX is not specified).

The following example shows Scratch Conversion utility output, without LIBONLY or TAPEPLEX specified:

Example 5-4 Scratch Conversion Utility output (without LIBONLY or TAPEPLEX)

StorageTek Enterprise Library Software Scratch Conversion Utility Page 00001
Time 12:15:39 Date 2010-03-31
SLS4723I Volume (VTV) 400021 used after SLUCONDB start or TODATE
SLS0286I 000005 volumes have been selected
SLS0155I Condition code for utility function is 0

The following example shows Scratch Conversion utility output, with LIBONLY or TAPEPLEX specified:

Example 5-5 Scratch Conversion Utility output (with LIBONLY or TAPEPLEX)

StorageTek Enterprise Library Software Scratch Conversion Utility Page 00001
Time 12:15:39                                                Date 2010-03-31

SLS2321I Volume A00020 successfully added to VSM as scratch
SLS2321I Volume A00023 successfully added to VSM as scratch
SLS0167I Volume FB2110 successfully added to library as scratch
SLS0167I Volume TIM021 successfully added to library as scratch
SLS2280I Volume 400021 selected after SCRATCH command USETOKN
SLS1312I 000004 volumes successfully scratched
SLS0155I Condition code for utility function is 4