SARSAM Standard Database Access Method

SARSAM is the database access method that allows user-defined programs running under MVS to access the database to retrieve index, SYSOUT, and panel data.
view
SARSAM is the database access method that allows user-defined programs running under MVS to access the database to retrieve index, SYSOUT, and panel data.
These subroutines provided to access the database:
  • SAMOPEN
    Open database.
  • SAMCLOSE
    Close database.
  • SAMGET
    Get index record.
  • SAMINVL
    Invalidate buffers.
  • SAMMSG
    Return error message.
  • SAMSOPN
    Open subfile.
  • SAMSGET
    Get subfile record.
  • SAMSCLS
    Close subfile.
  • SAMAOPN
    Open subfile.
  • SAMAGET
    Get auxiliary subfile record.
  • SAMACLS
    Close auxiliary subfile.
  • SAMDFMT
    Format date.
  • SAMTFMT
    Format time.
  • SARSAM
    Perform SARSAM access method request.
You can use standard calling conventions to call these routines, which can be called from any programming language (such as ASSEMBLER, COBOL, or PLI):
  • The address of a parameter list is placed in general register 1.
  • The return address is placed in general register 14.
  • The entry point address is placed in general register 15.
  • Note that a return-code is placed in general register 15 on exit from each routine.
The SARSAM routine provides an alternate, centralized method for calling the subroutines. The name of the subroutine is passed as the first parameter to the subroutine named SARSAM.
The high-order bit of the last parameter address pointed to by general register 1 must be set to one (if the called routine has parameters). This calling conversion is automatically supported by COBOL and PLI. With Assembler, the CALL macro must be explicitly coded with the VL parameter.
High-level language compilers might generate dynamic sub-program call logic.
It works as follows:
  • A dynamic call to a sub-program is not resolved at linkage editor time but instead it is resolved at execution time.
  • SARSAM must be statically linked with the application program.
  • SAMOPEN obtains storage areas which will contain control blocks that are required by subsequent calls to the other SARSAM functions such as SAMGET.
  • A dynamic call does the following:
    • Loads the sub-program at execution time
    • Execute the sub-program
    • Deletes the sub-program it when it returns to the main program
    Note:
    These actions cause the storage areas to be freed. The appropriate high-level language compiler option to force static linkage to sub-programs must be on.
Mapping macros (record definitions) for all index records for ASSEMBLER and COBOL programs are provided in the CA View CAI.CVDEMAC library.
The SARSAM Sample Programs can be installed using SMP/E or assembled/linked into a load library. JCL for the non-SMP/E method is included in the documentation for each sample program. A sample SMP/E procedure, BRMSSAMX, is provided in CVDEJCL which can be modified and used to install the SARSAM Sample Programs which are also in the CVDEOPTN Library. The procedure must be modified based on the SARSAM Sample to be installed.
To implement SARSAM8(ADLIST) using SMP/E, follow this example:
Change the USERMOD name and add a description to agree with the SARSAM sample number.
++USERMOD(BRMSSAM#) DESC(.......sample description......) .
to:
++USERMOD(HBRMSAM8) DESC(ADLIST - Archive Date Reporting Utility (SARSAM8)).
Change the first INCLUDE statement to the correct SARSAM sample:
INCLUDE AHALOAD(SARSAM#)
to:
INCLUDE AHALOAD(SARSAM8)
Change the first ORDER statement, the ENTRY statement, and the ALIAS statement to the control section name of the SARSAM sample. Browse CVDEOPTN(SARSAM8) and find the control section name:
ADLIST CSECT
Then change the ORDER, ENTRY, and ALIAS statements from:
ORDER CSECT
...
ENTRY CSECT ALIAS CSECT
to:
ORDER ADLIST ... ENTRY ADLIST ALIAS ADLIST
Change the NAME statement to the correct SARSAM sample
NAME SARSAM#(R)
to:
NAME SARSAM8(R)
Change the ++SRC name statement to the correct SARSAM sample
++SRC (SARSAM#) DISTLIB(AHASRC).
to:
++SRC (SARSAM8) DISTLIB(AHASRC).
Copy the source for the SARSAM sample into this USERMOD following the ++SRC statement. Find the string '<<< COPY YOUR SOURCE HERE >>>', delete that statement and insert your code.
Change the RECEIVE and APPLY to the correct USERMOD name from Step 1.