JAMS Reference Manual

Chapter 4
Using the JAMS Callable Interface

This chapter explains how to call JAMS from a user written program. It also explains how you can have JAMS call your routines when certain events occurs.

4.1 Using The Callable Interface

The JAMS callable interface is provided so that you can integrate batch jobs into your application software. You can call JAMS routines which will submit a single batch job or display a menu of jobs and allow the end-user to select a job.

All of the capabilities of the JAMS submission interface are available from the callable interface. The person selecting by way of the callable interface will be prompted for parameters and report overrides in the same manner as a user of the JAMS_MASTER program.

4.1.1 Calling JAMS Routines

The JAMS callable interface conforms to the OpenVMS Procedure Calling and Condition Handling Standard. This conformance allows the JAMS routines to be called from any programming language which supports the standard. All of the Compaq supplied compilers support the OpenVMS Procedure Calling and Condition Handling Standard.

4.1.2 Using Item Lists

Because of the extensive and diverse nature of the arguments used by the JAMS routines, many arguments are passed using an item list.

An item list is an array of item descriptors. This array is defined and initialized in your application program and then the address of the item list is passed to the JAMS routine. An item descriptor consists of four fields, two fields are words (16 bits each) and two fields are longwords (32 bits each). The item list array is terminated by an item descriptor with zero in all fields.

The structure of an item list is the same for all programming languages, but the methods used to define an item list are different in every language. Please refer to your language specific documentation for information on how to define data structures such as these. The fields in an item descriptor are shown in the following table:

Field Size Function

Buffer Length 16 bits Specifies the length of input items and the maximum length of output items.

Item Code 16 bits An identifier. It specifies what this item descriptor is providing or requesting.

Buffer Address 32 bits Specifies the address of the input or output buffer. Some input item codes may use this field directly.

Return Length Address 32 bits For output item codes, this is the address of a longword where the actual length of the returned data is stored. For input item codes, this field is not used and should be set to zero.

Field	Size	Function
Buffer Length	16 bits	Specifies the length of input items and the maximum length of output items.
Item Code	16 bits	An identifier. It specifies what this item descriptor is providing or requesting.
Buffer Address	32 bits	Specifies the address of the input or output buffer. Some input item codes may use this field directly.
Return Length Address	32 bits	For output item codes, this is the address of a longword where the actual length of the returned data is stored. For input item codes, this field is not used and should be set to zero.

4.1.3 Linking with JAMSSHR.EXE

The JAMS callable interface is provided in the form of a sharable image. Your program must be linked against this sharable image in order to resolve references to JAMS symbols and routines. Since the JAMS interface is provided as a sharable image, when you install new versions of JAMS, you will not need to recompile or re-link your programs. However, the JAMS sharable image is not inserted into the default OpenVMS sharable image library so you must explicitly specify the JAMS sharable image when you link your programs. The following example shows how this is done:

$ COBOL myprogram.cob $ LINK myprogram,SYS$INPUT/OPTION JAMSSHR/SHARE [Ctrl/Z] $

4.1.4 Privileges

You do not need to have any special privileges to compile and link programs which call JAMS routines. You will need special privileges to execute the program. In order to execute a program which calls JAMS routines, the process which runs the program needs the privileges listed in the following table. You could also install your program with the required privileges.

Privilege Reason

SYSPRV Needed to gain write access to the JAMS data files. This could also be accomplished with ACL's.

SYSLCK Required to coordinate access to the monitor and schedule processes.

OPER May be required to submit jobs to the proper queue.

CMKRNL Required if your program will be submitting Jobs which run under a different OpenVMS username.

Privilege	Reason
SYSPRV	Needed to gain write access to the JAMS data files. This could also be accomplished with ACL's.
SYSLCK	Required to coordinate access to the monitor and schedule processes.
OPER	May be required to submit jobs to the proper queue.
CMKRNL	Required if your program will be submitting Jobs which run under a different OpenVMS username.

4.2 Sample programs

JAMS provides a number of sample programs which are located in JAMS_EXAMPLES:.

JAMS2100.COB

Illustrates the use of the JAMS_SCHEDULE_xxx routines. This prints a projected schedule.

JAMS3000.COB

Illustrates the use of the JAMS_HISTORY_xxx routines. This prints Job execution history.

JAMS_EXAMPLE.COB

This program is written in OpenVMS COBOL and demonstrates how to call the JAMS_SUBMIT_JOB routine.

JAMS_SCANLOG.C

This program is written in C and demonstrates how to write a JAMS_SCHCALLUSER routine. This routine is called by the JAMS_SCHEDULE process when events occur. The JAMS_SCANLOG is an example of scanning a Jobs .LOG file to determine if it was successful.

JAMS_SCHCALLUSER.COB

This program is written in OpenVMS COBOL and demonstrates how to write a JAMS_SCHCALLUSER routine. This routine is called by the JAMS_SCHEDULE process when events occur.

JAMS_DECALERT.C

This program is written in OpenVMS C and demonstrates how you could activate DECalert from a JAMS_SCHCALLUSER routine.

4.3 Routines

The following sections describe the routines available to your application programs. The format of the JAMS_SCHCALLUSER routine is also explained.

Contents

Index