SCT SIS Fetch Term Utility

Many programs require a term parameter as input to drive the program. This utility will fetch the current term based on the current date and will return it.

In actuality, input can be in one of three forms:

An actual term
Blank
A term displacement

In case (1), the utility simply returns the same term. It ensures that the year is numeric and that the term is Fall, Spring or Summer.

In case (2), input is blank (or 0). The routine will fetch the current term and will return it.

In case (3), a displacement from the current term (e.g., +1, -5, etc.) is given. The routine will determine the current term and will then determine the desired term based on the term displacement specified.

Output is the term desired and a return code. The output term is returned in the original input field. The return code is sent back in the second parameter field.

The routine is only useable in Easytrieve Plus. There are two include members that are used.

Include #1
The first include member is SI0900D. It contains the working storage fields and DB2 Declares necessary for the routines to work. It should be the last entry in your Files section (the last entry before your first Job statement).

This include uses an Easytrieve Plus Macro variable. This Macro variable is named SISVER and must be a Macro variable in the original program. It specifies the version of the SIS system from which the term is determined (BASE, TEST or PROD).

Include #2
This Include is named SI0900E. It does the actual work to determine the term. It takes two arguments:

Term Specification -- a 5 character field in one of 5 formats:
- CCYYT -- specifies an actual term to be used. The routine verifies format and returns it.
- blank -- returns the term term
- 0 -- Same as a blank
- +xx -- Returns the term xx terms in the future from the current term.
- -xx -- Returns the term xx terms in the past from the current term.
- This field contains the term to be used in a program after the routine ends.
Return Code -- This field is returned by the routine to indicate the status of the request. It can contain 2 values:
- NF -- The current date is beyond the range of and term defined in the calendar tables.
- 0 -- The term was successfully determined.

The SI0900E Include is invoked as follows:

%SI0900E xxx yyy

where xxx is the variable containing the term displacement and yyy is the variable containing the return code (at least 2 bytes).

Mechanics

This routine looks at the SIS calendar tables, as can be seen in the online SIS application CAL. It is possible that a given date falls between the end of one term and the beginning of the next term. The routine will attempt to reconcile this and return the upcoming term. However, the NF return code should be detected in case automatic reconciliation fails.

Once the current term is determined, the displacement factor (if any) is applied.

If an actual term is supplied, no calendar lookup is performed. Actual term input is determined by:

The first four bytes are numeric (representing the year)
The third byte is a term (W, S, M or F)
The fourth byte is blank or does not exist

JCL Requirements

No special JCL is required to use this routine.

Example

A sample program (call it TEST01) might look as follows:


MACRO SISVER
FILE FILE01
   WTERM             W           003 A   VALUE '+1'
   WRTNCD            W           002 A
  %SI0900D &SISVER

JOB INPUT NULL
  %SI0900E WQTR WRTNCD
  DISPLAY 'TERM=' WTERM
  DISPLAY 'RETURN CODE=' WRTNCD
  STOP

This is a very simplistic example of use of the SI0900E routine. It will return the term one term beyond the current term.

Limitations

If an actual term is input, the routine does not verify the existence of the specified term.
If input is invalid, the bytes that are invalid are treated as zeroes.
If no sign is specified on a displacement, it is assumed to be positive.
The range of term displacements is -9 to +9.

Technical
The SI0900E routine uses the SIS_CONTROL_TB (short name: ACRTTS) DB2 table in the SIS system. The checking of the ACRTTS table is done through Easytrieve Plus code that uses a SQL DECLARE CURSOR. The name of the cursor is FQCUR, which is defined in the SI0900D Include. It is this Include that uses the &SISVER Macro variable. This Macro variable contains the owner code of the DB2 ACRTTS table to be used, e.g., BASE, TEST or PROD).
All variables used by this routine have a suffix of ## to prevent duplicate variable names. Should a program using this routine use the same convention, see the SI0900D Include module for variable definitions.

OIT--Applications Support

Last Modified: Friday, 27-Feb-2004 10:10:51 CST
© 2004;All Rights Reserved

SCT SIS Fetch Term Utility

Mechanics

JCL Requirements

Example

Limitations

Technical