Unicenter CA-View SAR Standard Database Access Method (SARSAM) or "Do you have a utility to..."

Document ID : KB000055583
Last Modified Date : 14/02/2018
Show Technical Document Details

The standard packaging for Unicenter CA-View contains an access method, SARSAM, to read database control records, Sysout data and/or Page Separation data. The product also contains various sample programs which use SARSAM to produce various reports.

SARSAM consists of callable subroutines to open and close a Unicenter CA-View database, read Master Index records, and open, read, and close a database sub-file (Sysout data or Page Separation data). There are also two miscellaneous functions to invalidate input buffers and return formatted database error messages.

The functions available to an application program are:

Database Functions:
SAMOPENOpen a database
SAMGETGET a Master Index record
SAMCLOSEClose a database
Sub-file Functions (require an open database):
SAMSOPNOpen a sub-file
SAMSGETGET a sub-file record
SAMSCLSClose a sub-file
Miscellaneous Functions (require an open database):
SAMINVLInvalidate index buffers (Refresh)
SAMMSGConvert return code to message text

SAMGET provides facilities to read the Master Index either sequentially or directly. The SAMGET options are:

EQGet equal to
LTGet less than (Get previous)
GTGet greater than (Get next)
LEGet less than or equal to
GEGet greater than or equal to Open a database

The Unicenter CA-View database contains two major data types: a Master Index and data sub-files. The Master Index contains Unicenter CA-View configuration information (such as the initialization parameters), tape usage, panel information, user definitions and status, view and filter definitions, information concerning ACIF and/or Xerox resources, and information concerning report data.

The Master Index associated with the Unicenter CA-View database contains a wealth of control information about users, view definitions, and Sysout data. Record layouts of all of the database control records are available in the CAIMAC library. There is no specific documentation for these records, but comments on the various fields within each of the record layout macros specify the use and contents of the records.

The following is a list of the various control records and their access key values:

MCR  X'00000000000000000000000000000000'  MASTER CONTROL RECORDPCR  X'00000000000000000000000000000001'  PERMANENT ARCHIVE (ALSO KNOWN AS                                          EXTENDED RETENTION) CONTROL RECORDECR  X'00000000000000000000000000000002'  EXPRESS DELIVERY INTERFACE CONTROL RECORDSTR  X'00000000000000000000000000000010'  SAR INDEX STATISTICS CONTROL RECORDTCR1 X'000000000000000000000002........'  PRIMARY TAPE CONTROL RECORDTDR1 X'000000000000000000000003........'  PRIMARY DUPLEX CONTROL RECORDTCR2 X'000000000000000000000004........'  SECONDARY TAPE CONTROL RECORDTDR2 X'000000000000000000000005........'  SECONDARY DUPLEX CONTROL RECORDUCR  x'01..............................'  USER ATTRIBUTE RECORDOCR  x'02..............................'  ONLINE CONTROL RECORDVCR  x'03..............................'  VIEW CONTROL RECORDVCX  x'04..............................'  VIEW XREF CONTROL RECORDFCX  x'05..............................'  FILTER XREF CONTROL RECORDBTR  x'06..............................'  BASIC TEMPORARY RECORDACR  x'10..............................'  ALTERNATE INDEX RECORDDCR  X'11..............................'  DEVICE CONTROL RECORDSDR  x'20..............................'  SYSOUT DESCRIPTOR RECORDXDR  x'21..............................'  DISTID XREF RECORDPQR  x'22..............................'  PC TRANSMIT QUEUE RECORDFCR  x'23..............................'  FILTER CONTROL RECORDXTR  X'24..............................'  EXTENDED TEMPORARY RECORDRCR  X'3F..............................'  RESOURCE GROUP CONTROL RECORDGCR  X'40..............................'  GROUP CONTROL RECORD (GCR KEY IS > X'40.....')

These records normally contain all the information associated with a specific resource. For example, a Tape Control Record contains all the information pertaining to a Backup tape. Resources which require a variable amount of space, such as report data, require a Master Index record for the control information and a sub-file to hold the variable data. Records which contain information to access sub-file data are the On-line (Panel) Control Record, the Resource Group Control Record, and the Group Control Record. These records also contain the extent and block information to access the data associated with this data type.

The control record of most value for general reporting purposes is the Group Control Record (GCR). This record contains most of the sysout attributes, current sysout location, archival and print dates, last referenced date, report line counts and page counts, tape location information, user modifiable accounting and data fields, and Expanded Retention information.

SARSAM lets clients write custom reports or perform specialized tasks on the database. Unicenter CA-View does contain some canned reporting functions such as those provided by the Batch Processing program (SARBCH) or the Sysouts on Tape Utility (SARTSLST). Specialized needs do arise for an output management group to provide other statistics based on users, Sysout data, etc. SARSAM can provide a simple and effective way to extract information from the Unicenter CA-View database.

The following samples are based on actual client requests received by the Output Management Support team.

How many reports in the database are using the "ACCT" form? A report program using the database access method could be written to sequentially read all the group control records and print a detail line of each Sysout using this form number. The following is a condensed sample of a sequential read loop to accomplish this task:

****************************************************************        Open the Unicenter CA-View Database                  ****************************************************************         CALL  SAMOPEN,(VIEWDB),VL     OPEN THE DATABASE****************************************************************        Perform 'open' error checking                        *****************************************************************        Read the first Group Control Record                  **        "READOPT1" is set to "GE" to read the first database **        control record which is 'greater than' or 'equal to' **        a GCR with an ID of 'BLANKS':                        **                    MVI   GCRID,C' '                         ****************************************************************         MVI   GCRID,C' '              SET STARTING RECORD ID         CALL  SAMGET,(GCR,RECLEN,READOPT1,RECREAD),VL READ GCR****************************************************************        GET error checking                                   ****************************************************************         B     PROCESS****************************************************************        "READOPT2" is set to "GT" to read the next database, **        that is "GET NEXT"                                   ****************************************************************LOOP     CALL  SAMGET,(GCR,RECLEN,READOPT2,RECREAD),VL READ NEXT          LTR   R15,R15                 END OF FILE?         BNZ   EOD                     YES, BRANCHPROCESS  CLC   GCRFORM,=CL8'ACCT'      ACCOUNTING FORM?         BNE   LOOP                    NO, GET NEXT RECORD*        PROCESS REPORT DETAIL LINE    YES, PRINT REPORT DATA         B     LOOP                    GOTO GET NEXT RECORD****************************************************************        Close the Unicenter CA-View Database                 ****************************************************************EOD      CALL  SAMCLOSE                CLOSE DATABASE         etc.

Is there any way to search all the accounting reports in the database for a specific text string, like an account number or client name? In the above example we read all Group Control Records looking for a known form number. We can change that sample to read only Group Control Records which begin with a known report ID, such as, TF14nnnnnn. When we find reports with this naming convention, we can determine if the report is still resident on the database (SARSAM cannot be used to access report data unless it is on disk) and if it is, we can search each record of the report for the specific text string. In the following sample we'll add code to set a different starting point, look for either the end-of-file or a change in the report ID. We will open the report data sub-file and read and process the data:

*        housekeeping...         CALL  SAMOPEN,(VIEWDB),VL     OPEN THE DATABASE*        Perform 'open' error checking****************************************************************        "READOPT1" is set to "GE" to read the first database **        control record which is 'greater than' or 'equal to' **        a GCR with an ID of 'TF14' plus binary zeros:        ****************************************************************         MVC   GCRID,=XL12'00'       INITIALIZE REPORT IDs TO         MVC   GCRID(4),=CL4'TF14'   START WITH TF14         CALL  SAMGET,(GCR,RECLEN,READOPT1,RECREAD),VL READ GCR*        GET error checking         CLC   GCRID(4),=CL4'TF14'   ANY 'TF14' REPORTS?         BNE   EOD                   No, GOTO TERMINATE         B     PROCESS               YES, GOTO PROCESSLOOP     CALL  SAMGET,(GCR,RECLEN,READOPT2,RECREAD),VL READ NEXT RECORD         LTR   R15,R15               END OF FILE?         BNZ   EOD                   YES, BRANCH         CLC   GCRID(4),=CL4'TF14'   NO, ANY MORE 'TF14' REPORTS?         BNE   EOD                   NO, GOTO TERMINATEPROCESS  TM    GCRSWTCH,GCRONDSK     IS THE REPORT ON DISK?         BNO   LOOP                  NO, GOTO GET NEXT RECORD****************************************************************        Open the report data sub-file                        ****************************************************************         CALL  SAMSOPN,(GCR),VL OPEN SUBFILE*        Perform 'open sub-file' error checkingDATALOOP CALL  SAMSGET,(BUFFER,RECLEN,RECREAD),VL         LTR   R15,R15           EOD?         BNZ   DATACLS           YES, GOTO CLOSE SUB-FILE**        processing to scan each record for the text string*         B     DATALOOP          GOTO GET NEXT DATA RECORDDATACLS  CALL  SAMSCLS           CLOSE THE SUB-FILE         B     LOOP              GOTO GET NEXT GCR RECORDEOD      CALL  SAMCLOSE                CLOSE DATABASE         etc.

Can you delete all the reports associated with a transferred employee? There is no user identification information held in the Unicenter CA-View database unless a client has a custom Archival Task exit (SARSTCUX). There is a field defined in the GCR which can be used to save that information. The sample program below uses the first sample as a base, but changes it to select a GCR whose user field contains the employee's User ID. It then moves the Report ID, Generation and Sequence numbers to a preformatted /DELETE control card and writes it to a sequential output file. This file would be input to the Unicenter CA-View Batch utility SARBCH:

****************************************************************        Open the Unicenter CA-View Database                  ****************************************************************         CALL  SAMOPEN,(VIEWDB),VL     OPEN THE DATABASE*        Perform 'open' error checking                        *         MVI   GCRID,C' '              SET STARTING RECORD ID         CALL  SAMGET,(GCR,RECLEN,READOPT1,RECREAD),VL READ GCR*        GET error checking                                   *         B     PROCESSLOOP     CALL  SAMGET,(GCR,RECLEN,READOPT2,RECREAD),VL READ NEXT          LTR   R15,R15                 END OF FILE?         BNZ   EOD                     YES, BRANCHPROCESS  CLC   GCRUIF,=CL8'SMITH01'    BOB SMITH's REPORTS?         BNE   LOOP                    NO, GET NEXT RECORD*        PROCESS REPORT DETAIL LINE    YES, PRINT REPORT DATA*        *        MOVE GCR REPORT ID TO CONTROL CARD*        CONVERT GCR GEN FROM BINARY TO EBCDIC*          AND MOVE TO CONTROL CARD*        CONVERT GCR SEQ FROM BINARY TO EBCDIC*          AND MOVE TO CONTROL CARD*        WRITE CONTROL CARD TO OUTPUT FILE         B     LOOP                    GOTO GET NEXT RECORD*        Close the Unicenter CA View Database                 *EOD      CALL  SAMCLOSE                CLOSE DATABASE...CTLCARD  DS    0CL80         DC    CL11'/DELETE ID='CCRID    DS    CL12         DC    CL5' GEN='CCGEN    DS    CL5         DC    CL5' SEQ='

Can I extract all of the User Profiles from one database and add them to another? Working from the first sample, a program can be written to extract all User Attribute Records (UCR) and write them to a variable-length sequential file, which in turn could be "SARDBASE/LOADed" to another database. The following is a condensed sample of setting a read-loop starting with the first User Attribute Record and sequentially reading all user records, writing them to a variable-length file:

****************************************************************        Open the Unicenter CA-View Database                  ****************************************************************         CALL  SAMOPEN,(VIEWDB),VL     OPEN THE DATABASE*        Perform 'open' error checking                        **        Read the first User Attribute Record (UCR)           *         OPEN  (SYSUT2,OUTPUT)         OPEN UNLOAD OUT FILE         MVC   UCRKEY,=XL16'00'         MVI   UCRKID,X'01'            SET START AT FIRST UCR         CALL  SAMGET,(UCR,RECLEN,READOPT1,RECREAD),VL READ UCR*        GET error checking                                   *         B     PROCESSLOOP     CALL  SAMGET,(UCR,RECLEN,READOPT2,RECREAD),VL READ NEXT         LTR   R15,R15                 END OF FILE?         BNZ   EOD                     YES, BRANCH         CLI   UCRKID,X'01'            END OR UCR RECORDS?         BNE   EOD                     YES, GO TO CLOSE FILESPROCESS  LH    R2,RECREAD              LOAD UCR RECORD LENGTH         LA    R2,4(R2)                ADD VARIABLE LENGTH HDR         STH   R2,UCRLEN               STORE IN RECORD AREA         PUT   SYSUT2,UCRLEN           WRITE TO UNLOAD FILE         B     LOOP                    GOTO GET NEXT RECORD*        Close the Unicenter CA-View Database                 *EOD      CALL  SAMCLOSE                CLOSE DATABASE         CLOSE (SYSUT2)                CLOSE UNLOAD OUT FILE         etc.SYSUT2   DCB   DDNAME=SYSUT2,RECFM=VB,LRECL=6129,                      X               BLKSIZE=32760,MACRF=PM,DSORG=PS         DS    0DBUFFER   DC    32760X'00'         ORG   BUFFERUCRLEN   DS    H         DS    H         SARUCR DSECT=NO           RECORD KEY

Can I extract all of the Views and Filters from one database and add them to another? We can modify the previous sample to extract only the four record types which define all the views and filters:

         MVC   VCRKEY,=XL16'00'         MVI   VCRKID,X'03'            SET START AT FIRST VCR         CALL  SAMGET,(VCR,RECLEN,READOPT1,RECREAD),VL READ VCR*        GET error checking                                   *         B     PROCESSLOOP     CALL  SAMGET,(VCR,RECLEN,READOPT2,RECREAD),VL READ NEXT         LTR   R15,R15                 END OF FILE?         BNZ   EOD                     YES, BRANCH         CLI   VCRKID,X'03'            VIEW CONTROL RECORD?         BE    PROCESS                 YES, BRANCH         CLI   FCXKID,X'05'            VIEW OR FILTER XREF RECORD?         BE    PROCESS                 YES, BRANCH         CLI   FCRKID,X'23'            FILTER CONTROL RECORD?         BE    PROCESS                 YES, BRANCH         BH    EOD                     GREATER THAN X'23', BRANCH         B     LOOP                    NO, GOTO GET NEXT RECORD

Can I also read the page separation index values? Yes, the SAMSOPN (sub-file Open) function uses the GCR to determine the sub-file that will be opened. The GCR has two sub-file address fields, one for the report data and one for the page separation index data (also known as the Auxiliary Sub-File). There are three fields in the GCR which identify the location and extent of the report data sub-file. SAMSOPN will always open the sub-file pointed to by these three fields. The fields are:

GCRFDCCB - DISK ADDRESS OF FIRST BLOCK OF SUB-FILE (DCCB)
GCRLDCCB - DISK ADDRESS OF LAST BLOCK OF SUB-FILE (DCCB)
GCRLEOBO - OFFSET TO END OF BLOCK IN LAST BLOCK

There are also three similar fields which identify the auxiliary sub-file location and extents:

GCRAFDCB - DISK ADDRESS OF FIRST BLOCK OF AUXILIARY SUB-FILE
GCRALDCB - DISK ADDRESS OF LAST BLOCK OF AUXILIARY SUB-FILE (DCCB)
GCRALEBO - OFFSET TO END OF BLOCK IN LAST BLOCK OF AUXILIARY SUB-FILE

By moving the three auxiliary fields to the corresponding report sub-file fields prior to the SAMSOPN, we will be able to read the page separation data:

****************************************************************        Open the page separation index sub-file              ****************************************************************         CLC   GCRAFDCB,=F'0'   IS THERE AN AUXILIARY SUB-FILE?            BE    LOOP             NO, GO TO CONTINUE         MVC   GCRFDCCB,GCRAFDCB YES, MOVE AUXILIARY LOCATION         MVC   GCRLDCCB,GCRALDCB   AND EXTENT FIELDS TO THE         MVC   GCRLEOBO,GCRALEBO   THE REPORT SUB-FILE FIELDS         CALL  SAMSOPN,(GCR),VL OPEN SUBFILE*        Perform 'open sub-file' error checkingDATALOOP CALL  SAMSGET,(BUFFER,RECLEN,RECREAD),VL         LTR   R15,R15           EOD?         BNZ   DATACLS           YES, GOTO CLOSE SUB-FILE         CLC   BUFFER+1(3),=CL3'TCD' INDEX VALUE RECORD?         BNE   DATALOOP          NO, GO TO GET NEXT RECORD**        YES, PROCESS INDEX VALUE RECORD*         B     DATALOOP          GOTO GET NEXT DATA RECORDDATACLS  CALL  SAMSCLS           CLOSE THE SUB-FILE         B     LOOP              GOTO GET NEXT GCR RECORD

Are there any canned samples? There are samples provided in the CAISRC distribution library which are documented in the comment statements. With this article and the samples, you are now ready to start coding to meet your own special requirements.