Model 204
APSY and the SETGRC Command By James Damon
Error Handling Under APSY
This leads to uneven handling of error conditions unless you code procedures that take this behavior into account. To illustrate this error handling, consider Figure 1. Assume that the subsystem name is STAT, the non-precompile prefix is STATN, the precompile prefix is STATP and the error procedure is STATP.ERROR:
Figure 1. Examining the behavior of an error handler in an APSY procedure
PROC STATN.LOGIN RESET MSGCTZ 7 /* M204.1122: INVALID PARAMETER; does not INCLUDE STATP.ERROR VIEW MSGCTL /* executes normally RESET LECHZ 0 /* M204.1122: INVALID PARAMETER; does not INCLUDE STATP.ERROR VIEW LECHO /* executes normally BEGIN Procedure code ... %X = $SETG('NEXT','STATP.PROC1') END RESET MSGCTZ 0 /* M204.1122: INVALID PARAMETER VIEW /* executes normally RESET LECHZ 1 /* M204.1122: INVALID PARAMETER VIEW LECHO /* executes normally END PROC /* STATP.ERROR included here due to above errors
Figure 2. Examining types of command errors in an APSY procedure
PROC STATN.LOGIN UTABLE LSTBL 50000 /* Could fail sometimes leaving STBL at current setting. This in turn may cause the program to fail intermittently for some users with M204.0551: REQUEST TOO LONG - STBL. RESET MUDDZ 999999 /* M204.1122: INVALID PARAMETER If MUDD was set low prior to entry, some users may sometimes get M204.1332: LONG REQUEST USE OUTuserid Failure may occur for some users and not others. BEGIN Procedure code ... %X = $SETG('NEXT','STATP.PROC1') END END PROC
A facility exists that allows you to handle errors that result from commands issued in APSY and non-APSY procedures to ensure predictable results and to provide notification when predictable results cannot be guaranteed.
Introducing the SETGRC (SET Global Return Code) Command
The SETGRC command assigns to a global variable the value of the return code that was set by the previous command. Optionally, you can provide a second global variable that will be set to the text of the error message generated by the command failure. The syntax of the SETGRC command is:
SETGRC [rcglobal] [errtextglobal]
The rcglobal global variable is set to 0 if the previous command was successful; otherwise, it is set to 1.
If you require notification of the success or failure of a command issued prior to BEGIN in APSY procedures, the code in Figure 3 provides an example of how this might be done.
Figure 3. Trapping error codes with a SETGRC command
PROC STATN.LOGIN COPY PROC ASDF TO PROCFILE SETGRC COPYRC COPYETXT BEGIN IF $GETG('COPYRC') > 0 THEN /? IF COPY COMMAND FAILS ?/ PRINT 'COPY RC: ' WITH $GETG('COPYRC') PRINT 'COPY ERROR: ' WITH $GETG('COPYETXT') AUDIT 'COPY RC: ' WITH $GETG('COPYRC') AUDIT 'COPY ERROR: ' WITH $GETG('COPYETXT') %X = $SETG('NEXT','STATP.ERROR') STOP END IF If COPY successful then continue ... END END PROC
Note: Both PRINT and AUDIT statements are used in Figure 3 to guarantee that any error messages generated by this procedure are displayed not only to the user, but are also saved in CCAAUDIT for later examination, if needed.
The SETGRC command is not confined to use in APSY procedures. You may use it in any procedure, APSY or non-APSY, or as part of a series of inline commands to cause conditional execution of other procedures depending on the success or failure of a particular command. Figure 4 shows two examples of how you can use SETGRC anytime you require notification of the success or failure of a particular command:
Figure 4. SETGRC command examples
In Summary
Proper error handling at command level, whether in an APSY or non-APSY procedure, can be critical in debugging applications and in guaranteeing predictable results. Using the SETGRC command makes error handling much easier to deal with and should be part of any application that issues commands prior to or following the execution of User Language requests. You can find additional information on the SETGRC command in the Model 204 Command Reference Manual.
System 1032
System 1032: Lesser Known Features: Part 2
By Tym Stegner
Last month we began a series of articles on the lesser-known features of System 1032. This month we are looking at the day-to-day interactive operation of System 1032 and several performance tips.
Operating in an Environment of Lesser Known Features
This operations section examines commands and variables that tend to apply in an interactive environment.
Multiple Sessions
In the days before terminals with Windows, you could still have multiple sessions, even without access to multiple terminals. Using the DCL spawn command you can create subprocesses to give yourself multiple sessions under one login. In System 1032, the equivalent command is PUSH.
From your main System 1032 session, you might have an editing subprocess, a MAIL session, and a DCL window for testing. To navigate among these sessions, use the ATTACH command that transfers control from your current process to a specified process. (Some people start a TPU session, then spawn DCL and System 1032 processes from that.)
The subprocess quota limits how many subprocesses you can create. It is further limited by adequate byte limit. You cannot transfer control using an ATTACH command to a subprocess created via the System 1032 PUSH USING command, as the input channel to such a subprocess is a mailbox.
Similar to symbolic commands in DCL, in System 1032 you can create specialized commands via the COMMAND data type in the VARIABLE command. You can create customized extensions to the System 1032 syntax. A common use of this feature is a set of commands to widen and narrow the screen:
Once defined, you can shift the System 1032 screen to 132-character mode with the following command:
Opening Your Tool Chest
The MTOOLS files in the S1032_DEMO directory and the S1032_CMD.DML library in S1032_TOOLS are CCA-supplied demonstrations of the command definition facility. One example from MTOOLS is a redefinition of the OPEN command, which was designed to enhance OPEN, eliminate keywords, and perform lookups on specified catalog objects to determine location and accessibility of the catalog. In this case the command variable is defined to call a procedure, passing the OPEN arguments.
The S1032_CMD library provides DCL-like commands to facilitate DCL operations from within the System 1032 environment. DCL commands such as EDT, DELETE, PRINT, SUBMIT, TPU, and TYPE are included.
RESET SCREEN Is Not Just for Forms
While nominally used for System 1032 Forms operations, you can use the RESET SCREEN command to change the display width for interactive operations. The next RESET command not only shifts the screen to 132-character mode, but it also sets the default page width to 132 as well. This makes more of the screen available to PRINT commands.
1032> RESET SCREEN WIDTH 132 ! use 80 to switch back
The following RESET command can be used to wipe the screen without resorting to DCL tricks or escape sequences:
The following commands and procedures are used to limit user aborts within PL1032 procedures or command files.
As the name 'control ' suggests, using the PL1032 command SET CONTROL_C you can enable or disable the Control-C abort. In a similar fashion, using the CONTROL_C_CHECK and _TRAP tools procedures lets you effectively disable Control-C abort actions and to check whether the user entered a Control-C since setting the trap. Then programmers can perform their own Control-C handling.
Companies with international business data must contend with differently formatted date strings. System 1032 has great abilities to interpret date strings. However, out-of-the-box System 1032 formats and displays dates as Month-Day-Year, unlike the international standard which is Day-Month-Year.
Rather than reformatting international data, you can change System 1032 from Month-Day-Year to other dates, using the SET STANDARD command. This command accepts two options: AMERICAN or INTERNATIONAL. This SET command updates the value of the system variable $DATE_STANDARD.
1032> PRINT 'November 28, 1960' $TODAY $TODAY ---------- 11/28/1960 00:00AM 05/09/2003 1032> 1032> SET DATE_STANDARD INTERNATIONAL 1032> PRINT 'November 28, 1960' $TODAY $TODAY ---------- 28/11/1960 00:00AM 09/05/2003
There is a similar SET command for international numeric notation.
One of the cautions of System 1032 data operations is to look out for dataset damage. In egregious cases, when a potentially damaged dataset is updated, the dataset can be rendered unusable following a CLOSE command. When a damaged dataset is opened or updated, System 1032 notifies the user via a warning message, cautioning that this dataset is potentially damaged.
To further protect datasets, you can escalate this warning message to error status, thus preventing a potentially damaged dataset from being opened at all. To perform this escalation, assign the value TRUE to the system variable $DAMAGE_ERROR:
1032> LET $DAMAGE_ERROR = TRUE
From that point on in the session, damaged datasets cannot be opened. The OPEN command fails with an E-level error, rather than the default W-level warning.
To reestablish the ability to open, and thus fix, a damaged dataset, reassign the $DAMAGE_ERROR system variable with the value FALSE.
Performance Tips
This section of lesser-known features and functions focuses on commands to facilitate data uploading efficiency and update and query efficiency.
Sorting Only Once
When a dataset is initially loaded or undergoing a bulk update via an APPEND command, System 1032 collects the data values for any keyed attributes, ships the data to the VMS sorter for ordering, then processes the key table updates from the sorted data.
In some cases, the input file may already be in a sorted order based on a primary key. To reduce the overhead of the LOAD or APPEND operation, you can designate this already sorted primary key as PRESORTED. Using this option saves System 1032 the time and disk space of resorting this attribute.
Storing Data of Varying Length
You can define varying length text attributes in System 1032. This is a convenience feature in System 1032, not an efficiency feature, because the Text Varying data type requires additional storage and uses more update overhead than does a fixed-length text attribute.
This being said, you can maximize the efficiency of text varying data storage by examining how often the attribute is updated. Using a command similar to the following demonstrates the use of the UPDATE option for an attribute of type Text Varying that is not to be updated after initial load:
DDL> ATTRIBUTE VX1 TEXT VARYING UPDATE NEVER
The UPDATE option has four options:
Choosing an update option that correlates to the intended update frequency allows System 1032 to store text varying data in the most efficient way by controlling the amount of free space left in the text varying value chains in the dataset.
Delegating the Work Load
One of the best methods of accelerating the I/O of a System 1032 database operation is to spread the data access across more than one disk. System 1032 performs many I/O operations in asynchronous form; by addressing more than one disk, the I/O load is also spread across multiple disks. For most applications, positioning the datasets among multiple disks is helpful. Try to place the most frequently accessed dataset(s) on your fastest disk.
You can also break the components of datasets across disks. In System 1032 you can break a dataset into its component parts, each into its own disk file.
Extracting keys and records is done via the KEY_DEFAULTS and LOAD_DEFAULTS sections of the dataset definition. Therefore, determining how keys and records are stored must be done when the dataset is created.
Sharing a Library Among Users
If you have a System 1032 application that is used by many people, you can gain efficiency by using the SHARE command. The SHARE command marks the procedures in one or more libraries as sharable, offloading the common parts of the compiled procedure code into an external file.
When the logical name specifying this file is installed (using the LIBUTIL program), this common procedure code is then available to all processes on the system via global memory, rather than using process memory.
You must define a logical name to reference the external file. Once available, the logical is used by the SHARE command as the target for the common code, as shown in the following code.
$ DEFINE REG_CODE DISK$SYS1:[REGFY04]S32CODE $ S1032 1032> OPEN LIBRARY REGMASTER in FY04_LIBS 1032> SHARE IN REG_CODE LIBRARY REGMASTER 1032> EXIT $ DIRECTORY REG_CODE Directory DISK$SYS1:[REGFY04] S32CODE.DMP Total of 1 file. $
Once the DMP file is created by use of the SHARE command, the code file must be placed into global memory using the LIBUTIL program, available in the S1032_IMAGE: directory.
Updating in Bulk
The precursor to System 1032, System 1022, had a bulk update method. The command was TRANSACT, which applied changes to and/or added records to a master dataset from corresponding records in a transaction dataset. Up to four locators were used to match corresponding records. You could specify Numeric attributes as ADDITIVE. A NO__CHANGE__BLANKS qualifier could be activated to prevent master dataset values from being updated if the corresponding transaction attribute value was zero, blank, or missing.
This TRANSACT command was not implemented in System 1032. Instead, a tool called TRANGEN was created that generates a FORTRAN program to perform similar operations. In brief, the TRANGEN tool requires a transaction dataset that contains the attributes to be updated, as well as up to four attributes that are used to locate the master records to be updated.
With both datasets open, the TRANGEN command is issued and that generates all the necessary files to create an application to update the master dataset from the transaction dataset. Records in the transaction dataset are nominally expected to be updates to the master dataset, but record addition and deletion are also supported.
More information about the TRANGEN tool will be found in an upcoming edition of CCAPrint.
Timing Update I/O
The $FLUSH_DELAY system variable controls the number of seconds that elapse before System 1032 writes modified internal buffers to data files on disk during the execution of command groups. The default is 10 seconds. To hasten posting of data to files, assign a lower number of seconds to the $FLUSH_DELAY system variable. A value of 0 tells System 1032 to post only at the end of a command group.
Modifying this system variable affects the I/O load of your System 1032 processing, so vary the value and compare benchmarks to see which setting works best for your application.
The $UPDATE_RETRY system variable controls the maximum time during which System 1032 will attempt to start an update command after an access conflict for a catalog has been detected.
Although the individual tips and suggestions described in this article might not dramatically change how your applications function, taken together they may smooth out the daily operation and make your applications run more easily.
Copyright © 2008 Computer Corporation of America. All right reserved. Published in the United States of America.
Contact CCA Webmaster Copyright 2008
