Group W Toolset Documentation

Table of Contents

Disclaimer and License

   
              D I S C L A I M E R   A N D   L I C E N S E   

      THiS SOFTWARE IS PROVIDED WITHOUT CHARGE ON AN "AS IS" BASIS. 
      AS SUCH, WARRANTY IS NEITHER EXPRESSED NOR IMPLIED.   

      IT IS EXPECTED THAT THIS PROGRAM WILL BE CAREFULLY EVALUATED  
      AS TO SUITABILITY AND CORRECTNESS BY AN EXPERIENCED UNISYS
      1100/2200 INTERNALIST BEFORE BEING USED.  THE AUTHOR(S) AND/OR
      AGENT(S) OF THE AUTHOR(S) ASSUME NO LIABILITY FOR DAMAGE  
      DIRECTLY OR INDIRECTLY CAUSED BY THIS PROGRAM, INCLUDING BUT  
      NOT LIMITED TO CASES WHERE SUCH DAMAGE RESULTS FROM PROGRAM   
      MALFUNCTION, PROGRAM DESIGN DEFICIENCY, INACCURATE OR 
      INADEQUATE DOCUMENTATION, IMPROPER USE, OR DESIGN/CODING  
      CHANGES IN 1100/2200 HARDWARE OR SOFTWARE SYSTEMS.

      USE OF THIS PROGRAM IS AT YOUR OWN RISK.  IF YOU ARE NOT SURE 
      OF WHAT YOU'RE DOING, IT IS STRONGLY RECOMMENDED THAT YOU NOT 
      USE THIS SOFTWARE.

      THIS SOFTWARE WAS DEVELOPED ON OUR OWN TIME.  OUR PAST AND
      PRESENT EMPLOYERS ASSERT NO OWNERSHIP AND ACCEPT NO   
      RESPONSIBILITY.  THIS SOFTWARE IS IN THE PUBLIC DOMAIN.   
      AS SUCH, YOU MAY DO WITH IT AS YOU WISH.  HOWEVER, WE WOULD   
      APPRECIATE IT IF YOU ACKNOWLEDGE OUR CONTRIBUTION SHOULD YOU  
      USE OUR WORK. 

About Group W (with apologies to Arlo Guthrie)

Group W is three Unisys 1100/2200 systems programmers who worked together for many years in eastern Canada. We hope you find some of the programs here useful and we encourage your comments, bug reports and New Feature Suggestions. You may contact us:

   
       Steve J. Martin (aka SJM)       sjm atsign superiorbeing.ca  
                                       http://www.superiorbeing.ca  

       Tom Nelson (aka THN)            Retired. 

       Bill Toner (aka WJT)            Retired. 

Advantages of This Package

• It is developed and tested by three different programmers with access to several 2200/Dorado machines. This allows us to test on various System Bases, configurations and hardware. Some well-known third-party vendors don't test as widely. Because there are three of us, the probability that you will come to rely on programs without an owner is reduced (but not to zero).
• It is released in a controlled manner. We never create sideline versions and don't approve of others doing so. Each processor displays its own release level and includes a history of changes at the top of its main source module. The entire Group W Toolset has its own release level (loosely analogous to a System Base release).
• We always release source code. We refuse to release absolutes only and we do not distribute parts of the package. This guarantees that you will not come to rely on programs for which you were not given source code. In those few cases where we cannot include all source because of copyright (e.g., Unisys' MCB copy procs), we don't release an absolute either; you are required to supply the missing copyrighted source and then compile the processor. This protects us from copyright violations and protects you from lacking source code for your executables.
• The source code serves as a good training tool, particularly for beginning MASM programmers. None of our MASM code is tricky and we avoid most complex meta-assembler directives.
• The Group W Toolset remains a going concern. The first version was released in 1992 as UPLI package #1099. One of us still works in 1100/2200 technical support every day.

Important Notes

1. Proprietary Data Structures

Many of the programs in this package read Exec-8 data structures and so are subject to failure if Unisys modifies these in future Exec levels. The versions included here are being used on System Base (SB) 19.0. Most of them also work on many lower System Base releases. Some of them use conditional assembly to generate the correct code for different Exec levels; you may have to change a MASM tag value and re-assemble for your Exec. Others benefit from the stability of the data structures they read. A couple are even smart enough to determine at run-time what Exec you've got and act accordingly (RUNINFO). You can find information about configuration issues for specific programs in the descriptions below and in the comments at the front of the code.

2. What We Mean by 'Toolset'

We use the term 'toolset' in the name of this package to stress that we're presenting a set of integrated tools. Many processors use the same procs and subroutines. We try to design our modules to provide a general facility that can be used for many purposes, rather than to solve only one specific problem (of course, we don't always succeed).

3. What We Mean by 'Pipelining'

Some of the processors here make use of "pipelining" (which is analogous to the Unix pipe operator and has nothing to do with methods used to speed instruction execution in processors). A full description of this concept can be found in Simulating Unix Pipelines, UNISPHERE, March 1993. In short, many of these processors read an Exec data structure and pipe the information to another program (often an SSG skeleton) through a temporary file with @USE name PL$$. This allows us to isolate the low-level Exec-dependent code (written in MASM) from the reporting or decision making code (often written in SSG). Such processors are identified by 'PIPE' or 'PL' in the processor name. Demand users would not normally use these processors directly, as they're designed to be invoked by other processors.

4. What We Mean by 'Generic Processor'

Some of the processors here are what we call a 'generic processor' (although 'general-purpose processor' would probably be a more accurate term). The generic processor is a MASM program that reads up to nine fields on the processor call and pipes them, along with the options mask, to an SSG skeleton which does the real work. The same generic processor absolute is installed as various processors. After writing the pipeline (PL$$) file, the generic processor determines the absolute name under which it's being executed and does: @ADD SYS$LIB$*LOCALRS.xxxxxx/ADD (where xxxxxx is the absolute name). Since this @ADDed element itself can contain processor calls, we use this facility to write 'macro-processors' (i.e., processors that invoke other processors).

5. Comments on these Techniques

Pipelining and generic processor techniques are not the most machine efficient way of implementing utility processors. It takes a lot more system resources to run a pipelined generic processor than it would if we just wrote the whole thing as a big MASM program. But these processors often tend to be low-use and for many purposes their performance is adequate. Although we're quite at home in assembly language (and even like it!), generic and pipelined techniques often allow us to provide more general functionality while taking less time to develop and test. There are some cases where we could've used these techniques but chose not to: For example, @I tends to get used often in demand so we wanted it to be as efficient as possible.

6. What We Provide

Several processors (@e for all programs and, with a couple of exceptions described below, also provide relocatables, absolutes, and/or object modules. Most of the absolutes will run for you without being re-assembled and re-collected. Each proc or program has an element with version name of 'ECL' which re-compiles it. For example, the ECL to re-compile the MUSER processor is in the element called MUSER/ECL.

7. Notes About MCB

Three processors (@PASOFF, @PIDSTA, @UDMDEL) use Message Control Bank (MCB). The default executables are configured for Application Group 7. For other AGs, you must customize these symbolic elements before re-compiling:

• ASGUSE (@USE for MCBLIB$)
• GETMCBBDI (Application Group flags around line 50)

Thanks to Gary Markowski for improvements to the packaging of our MCB code.

8. How to Get Help

You can get help with a processor's syntax (but not with semantics or pragmatics) by calling it with the 'H' option. Example: @MUSER,H

9. Note to Users Who Received this Package Electronically:

If you received this package via ftp or e-mail, it came as a self-extracting FTPack file. (Much thanks to Les Leist for the brilliant @FTPACK.) To extract the Group W Toolset:

   
    1.  Save the GWTS.ZIP file to your hard disk.   

    2.  Unzip the GWTS.ZIP file into GWTS.TXT.  

    3.  Upload GWTS.TXT in ASCII mode to your 2200 system (any filename).   

    4.  @CAT,P  GROUPW*TOOLSET(+1).,F///2000

    5.  @ASG,AX GROUPW*TOOLSET. 

    6.  @ADD your2200file.  

    7.  Results will be in GROUPW*TOOLSET.  See the READ-THIS element.  

10. Deleted Programs

As of Group W Toolset 5.0, these obsolete programs are no longer distributed or supported in any way:

• MASM-based @SYSID 2R5C is replaced by the generic processor @SYS. But note that this lacks support for the R option.
• MASM-based @PCT 4R2 is replaced by the generic processor @PCT. But note that this lacks support for several old options (D, L, N, P, X); @PCTPL supports piping PCT data.

11. Other Free Software We Recommend

As the number of 2200 sites diminishes, there is less available free software. We still recommend these packages:

• Ward Condit wrote a brilliant, fully-featured, free (for non-commerical use) OS2200 emulator that runs on Windows. It is distributed by Unisys (google "ClearPath OS 2200 Express") and is intended for hobbyists and and educational purposes.
• Les Leist has a large suite of terrific tools of his own, and he has been enhancing and maintaining some old classics (BK1/BK2, CPMD, DMP, DOWN, FLIST, FSED, MFD, TOCED). To get these tools, visit his Web site.
• Ward Condit's @ZIP has become a classic 2200 utility. It is available at Les Leist's Web site.

Release Matrices

The following table lists the dates on which each Group W Toolset release was issued.

The following table summarizes which versions of major modules (processors, programs, subroutines, skeletons) were included on selected Group W Toolset releases.

Contents of the Distribution File

Configuration Elements

ASGUSE

This element contains @ASG and @USE cards that specify the location of the source, relocatable, absolute, etc. files to be used when building the non-SSG parts of the Group W Toolset. The default for all Group W elements is a file called GROUPW*TOOLSET. Note that the default MCB is Application Group 7. You might need to change this.

---

GWTS-CONFIG/SGS

This element contains SGSs that provide site-defined configuration data for all SSG procs and generic processors. This element is copied to the LOCALRS file. Since SGSs are read at run-time, changes to this element take effect immediately.

---

SCREENSIZE/SGS

This element defines screen size for non-breakpointed demand runs. Screen size can be defined for user-id and/or site-id. This element must exist. If no definition is found for a demand run, screen size defaults to 24 lines of 80 columns. The sample provided has no customizations, so screen size will be 24 x 80 for all demand runs. This element is copied to the LOCALRS file. Since SGSs are read at run-time, changes to this element take effect immediately.

MASM Procs

IDLINE

This MASM proc builds and prints a processor identification line.

---

JBATCH

This proc jumps to the tag given on the proc call unless the run is demand non-breakpointed.

---

MCBDEF-MASM

This definition-mode MASM routine defines fields in the packet used to call the Message Control Bank (MCB). Source code for this proc is on the MCB release tape. We include only the omnibus here.

---

MFDDEF

This definition-mode routine defines Master File Directory data structures (lead item, main item, DAD tables). It works for Exec 46R6, and, we think, all SB 4 and above releases.

---

PIPE$PROCS

This definition-mode routine is common code for MASM programs which pipe output. It will be used more heavily in the future.

---

QWMODE

This MASM proc sets quarter-word mode.

---

RESREG

This MASM proc restores A,X,R registers.

---

RIBUFDEF

This MASM definition-mode routine defines fields in the data structure returned by RUNINFO. It is for RUNINFO.

---

SAVREG

This MASM proc saves A,X,R registers.

---

TWMODE

This MASM proc sets third-word mode.

Fortran Procs

BITMSK

This defines j-designators for Fortran, plus some bit shifting operations. It makes it easy for MASM programmers to bit-twiddle in Fortran!

---

DMSPAG

This defines data structures in a DMS page (the page header and the DARP page zero Dynamic Area Expansion table).

---

ELTTAB

This defines the fields in the Element Table (ELT$) using names that are familiar to MASM programmers.

C Headers

SHA1/H

This header is used by C function SHA1.

SSG Procs

CHECK-ERRCNT

Not all serious SSG errors terminate skeleton execution. This is (supposedly) a feature. This proc *ABORTs if ERRCNT$ is set and it is a non-demand run. It can be *COPYd as the last executable line in critical skeletons.

---

DAY-OF-WEEK

This element is a modified version of the proc found on the SSG 23R1 release tape and documented in Appendix C of the SSG Programmer Reference manual. It returns the day-of-the-week for a given input date. This version accepts a six- or eight-digit date and will work until 2099.

---

DEMAND-ONLY

This element checks whether a run is a batch or deadline batch run and, if so, *ABORTs. This ensures that a processor can be used only in demand.

---

EDIT-NUMBER

Given a number and a required output length, this routine returns a right-justified, comma-delimited character field (EDITED_NUM) suitable for display.

---

FILE-SPEC

This element accepts a field number (1 to 9) and returns the full file specification for that field (as specified by FIELD SGSs) on the generic processor call. Global character variable USERFILE will contain the file specification; global numeric variable FX will be set to the occurrence number in the FIELD SGSs representing where the requested field was found; global variable FXF will be set to the occurrence number in the FIELD SGSs where the filename was found (this will be equal to FX unless the filename is implied from a previous field via the comma-dot syntax construct). If the specified field is not found, USERFILE will be returned as a null string, and FX and FXF will be returned as zero.

---

GET-EXT-DATE

Given an International Standards Organization (ISO) 8601 internal date (YYYYMMDD format), this routine returns an external date in the site's standard format as defined by the GWTS_DATE_FORMAT and GWTS_DATE_SEP_CHAR SGSs in the GWTS-CONFIG/SGS element. If no input is provided, the current date is used.

---

GET-EXT-TIME

Given a time in HHMMSS format, this routine returns it in HH:MM:SS format.

---

GET-TS

This routine returns a current timestamp (format YYYYMMDDHHMMSSTTT) that avoids the problem that could occur if midnight is crossed between multiple DATE$ and TIME$ SGS references.

---

SCREEN-SIZE

This SSG *COPY proc uses SCREENSIZE SGSs to integer variables SCREEN_ROWS and SCREEN_COLS, which some skeletons use to control output for non-breakpointed demand.

---

SETUP-FIELDS

This SSG *COPY proc creates global variables from RELATION SGSs. See A Relational Approach to SSG, UNISPHERE, December 1992, for more information on the use of RELATION SGSs.

---

SET-ADD-FLAG

This SSG *COPY proc returns character variable ADD_FLAG as Y or N, depending on whether the generic processor was invoked within an @ADD.

---

SET-DEST

This SSG *COPY proc sets global variable DEST to 'Z' or 'O', depending on whether the skeleton is running in demand or batch, respectively. This enables *ACCEPT and *DISPLAY statements to be directed to the demand terminal or system console.

---

SHOW-ID-LINE

This SSG *COPY proc displays an identification line for processors written in SSG.

MASM Subroutines

CVTFDBIN

This MASM subroutine converts a one to six character Fieldata number to binary.

---

FTN-ER

General service routine for ASCII Fortran programs.

---

GETMCBBDI

This MASM subroutine returns the BDI for the MCB associated with a given Application Group. By default this is configured to work for Application Group 7. You must update the configuration tags to indicate which MCBs you want this to work for. Then you must re-assemble this routine and the processors that use it (@PASOFF, @PIDSTA, @UDMDEL).

---

INFOR

INFOR Table service routine for ASCII Fortran programs.

---

ISITXPA

This MASM subroutine returns 1 (binary) in A0 if it's an Extended Processing Architecture (XPA) system; otherwise, it returns zero in A0. This routine relies on the fact that Core Block SUPs will always be zero on an XPA system.

---

INSPSYSRUNS

This MASM subroutine performs a call to INSP$RUNS. Only @RUNPL calls it.

---

LONGWAIT

This MASM subroutine waits for long periods of time (i.e., longer than the ER TWAIT$ maximum of 30 seconds).

---

PIPELINE

This MASM subroutine assigns, opens, writes and closes the pipeline file. The pipeline file is a temporary (@ASG,T) file with name PL$$xxxxxx (where xxxxxx is the processor name); an an @USE name of PL$$ is also attached. For more information on pipelining, see Simulating Unix Pipelines, UNISPHERE, March 1993.

---

RUNINFO

This MASM subroutine returns a data structure containing various fields describing attributes of the calling run. RUNINFO gets this data via ER INFO$ when it can and ER PCT$ when it must. Thus, RUNINFO is sensitive to the Exec level it runs on. This version of RUNINFO returns nanosecond SUPs (available from Exec 44R3 and higher); for Exec levels lower than 44R3, it returns SUPs as zero. To the extent possible, we plan to update RUNINFO with each PCT format as Unisys changes it from SB5R3 forward, so that RUNINFO can determine at run-time the correct PCT format for the given Exec level. You may need to modify this routine for new Exec levels. We would appreciate notification of any updates you make for your site so we can incorporate them.

Fortran Subroutines

OCTDMP

This ASCII Fortran subroutine produces an octal dump of a caller-supplied buffer. It'll also provide ASCII and Fieldata translation. Rather than side-by-side a la FANG, it places the translation directly under the octal to which it applies.

COBOL Subroutines

BIN2OCT

This UCS COBOL subroutine accepts a word and returns 12 ASCII characters representing the octal interpretation of the word.

---

OCTALDUMP

This UCS COBOL subroutine produces an octal dump of a caller-supplied buffer. It'll also provide ASCII translation.

C Functions

SHA1

This UCS C function accepts ASCII data and computes the SHA-1 hash.

MASM Programs (@XQT)

PRTCN

This MASM program takes input data cards and submits them via ER PRTCN$, thus allowing you to @ADD transparent (@@) control statements in demand. It is the only program (as opposed to processor) in this file--you must @XQT it. It does not support the 'H' (help) option. Here's an example of how you can use it:

   
      @XQT file.PRTCN   
      d,@@ins 18
      @EOF  

MASM Processors

@AC

This MASM processor tells you what type of access you have to a given catalogued file without actually attempting any file access. It is for Security Option 1 (and above) sites only.

---

@ASGCNT

This MASM processor tells you how many runs have a particular catalogued file assigned. It optionally pipes this information. The FF keyin is preferable for console and @@CONS users, but this processor allows you to write smart batch jobs that vary their action depending on how many runs are using a file.

---

@DBACK

This MASM processor deletes the backup information for a file from the MFD.

---

@DISKPL

This MASM processor reads the unit tables and pipes data about your system's disk drives. @DAD and @DISK use this pipeline.

---

@DMSERR

This MASM processor displays the English description of Data Management System (DMS) 1100 internal, external and rollback errors, plus DMS command codes and Universal Data System (UDS) reasons for queuing. This is for UDS/DMS released with SB 4R6, but is fairly accurate for any recent release of UDS/DMS. We'd much appreciate corrections or updates to the text.

---

@DWTIME

This MASM processor decodes two twelve-digit octal DWTIME$ words into a readable form. This is very handy when looking at dumps.

---

@EACQ

This MASM processor does an "extended acquire" to allow you to position extents of a disk file on the pack you want. @EACQ supports sector- and word-addressable files (MSAR's @ACQ supports sector-addressable only). Example:

   
      @cat,p   file.,fmd///20000,rem201/rem202  
      @eacq    file.,0/10000,rem201      . allocate trks 0 to 9999  
      @eacq    file.,10000/10000,rem202  . allocate trks 10000 to 19999 

---

@FREEA

This MASM processor is used to free all from a demand run. It is a much-modified (stripped down) version of one of the many versions of FREEM used at numerous sites. Its major modifications are that it has code to handle the freeing of files assigned by the @Q processor and code to not free a run's Working Set files (for XPA systems). There is no 'H' (help) option for this processor. The 'S' option will suppress the list of files freed.

Note Well: @FREEA has a bug whereby it will go into an endless loop when it tries to @FREE the +1 cycle of a temporary file. This is rare because no sensible program does '@ASG,T fn(+1)'.

---

@GENER8

This processor takes the pipeline produced by @FASPL/@SELECT and generates commands (ECL or otherwise) in TPF$.ECL. For example, if you want to delete the files selected by @SELECT or @FASPL:

   
    @GENER8 
    #DELETE,C [*QFC].   
    @EOF
    @ADD ECL

---

GENERIC

This is source code for all generic processors. It reads and pipes INFOR (Internal Format) table data to PL$$xxxxxx and then @ADDs SYS$LIB$*LOCALRS.xxxxxx/ADD (where xxxxxx is the name of the absolute under which this processor is called).

---

@I

This MASM processor is a shortcut into IPF full-screen mode. For example, instead of:

   
    @IPF  file. 
    OLD   element/version   
    MOD SCR 

you can use:

   
    @I    file.element/version  

Optionally, you can specify that @I force IPF to position you at other than the top of the element by having it submit a LOCATE or BOTTOM command.

---

@KEYIN

This MASM processor submits console keyins by starting a demand run via ER RSI$ and then using @@CONS. You must use SIMAN to create a user-id with the appropriate privileges and then re-assemble @KEYIN with that userid/password. The default user-id password is KEYINU/KEYPAS. Please read the extensive comments at the top of this program for more information on how to set up its user-id and other important configuration issues.

---

@MANGLE

This MASM processor encodes any sector-addressable SDF disk file into an ASCII sector-addressable SDF disk file. The ASCII file format is ideal for file transfer and e-mail. The 'D' option will decode an @MANGLEd file back to its original form. This processor is analogous to the Unix utilities uuencode and uudecode (but its algorithm is different).

---

@MCTPL

This MASM processor pipes fields from the Master Configuration Table (MCT). @SYS uses this pipeline.

---

@MFDPL

This MASM processor pipes a file's (or, optionally, all f-cycles for a file) MFD data (lead item, main item and/or DAD tables). This is a work-in-progress: there are many MFD attributes it doesn't yet handle. @CYC and @DAD use this pipeline.

---

@MUSER

This MASM processor reads or sets a file's site use (MUSER$) cell in the MFD. You can later use FAS to select files with a given site use cell value. See also @TAG.

---

@PASOFF

This MASM processor reads a TIP transaction from a card and passes off to a given PID via a given MCB. The default absolute is for Application Group 7. For other Application Groups, see the discussion of GETMCBBDI.

---

@PCTPL

This MASM processor pipes various information about the run from the Program Control Table. Only PCT fields not available in SSG system-defined SGSs are piped.

---

@PIDSTA

This MASM processor reads a PID's current status for a given MCB and pipes this data. The default absolute is for Application Group 7. For other Application Groups, see the discussion of GETMCBBDI.

---

@PSWCHG

This MASM processor submits via RSI$ a password change request. Please see the extensive configuration notes at the top of the source. You may need to re-configure it for your site.

---

@Q

This MASM processor attaches @USE names and assigns each file in a symbiont queue (or each symbiont file for a given run-id). This enables you to edit PRINT$ files. Optionally, this processor will pipe this data to other programs. Please read the comments at the top of this processor.

---

@QCNT

This MASM processor shows and/or pipes the total number of symbiont files queued.

---

@QDEL

This MASM processor deletes symbiont queue entries (for a specifc print queue or a specific run-id) that have their "in progress" bit set. The "in progress" bit can be set with @QPIPE. See QCOPY for a sample batch job that uses @QPIPE and @QDEL to move print files from a symbiont queue to symbolic elements in a program file. See also @QC.

---

@QDISP

This MASM processor shows and periodically updates a screen displaying the first 19 entries on a symbiont queue. This is for demand runs only.

---

@QPIPE

This MASM processor is a variant of @Q. It allows the user to input ER SMOQUE$ mode bit settings to direct SMOQUE$ processing. For example, you could direct that "in progress" bits be set. See QCOPY for a sample batch job that uses @QPIPE and @QDEL to move print files from a symbiont queue to symbolic elements in a program file.

---

@RDMPPX

This MASM processor rewrites the page pointers in an RDMS area. It allows an area with all chains corrupted to be unloaded (via SQL UNLOAD) to a flat file, which can subsequently be sorted on primary key and reloaded. This is meant to be used only when your RDMS area is so badly corrupted that you've got nothing to lose. Use this strong medicine for no less an ailment and only under a doctor's strict supervision!

---

@RDSCQ

This MASM processor reads concurrency counts of Step Control queues and pipes them. This works only for simple single-level queue structures. It allows you to monitor usage of Step Control queue items conveniently. @QITEM reads this pipeline and displays readable output.

---

@SIPSTA

This MASM processor shows the status of the Software Instrumentation Package (SIP). It's similar to the SB STATUS keyin, but provides more readable output. The 'P' option will cause @SIPSTA to pipe some of the SIP status data.

---

@SPY

This MASM processor invokes @@CONS and uses Monitor Services to show the console keyins entered at all (system and remote) consoles. Being able to see the console keyins entered by other users can be very handy, especially for technical support staff. Two very important notes:

• @SPY uses ER SERVE$, which is a secured ER. In a Fundamental Security system, only the Security Officer has this privilege.
• To avoid accidentally re-transmitting keyins that @SPY shows you, we suggest you always execute it with the 'S' (safe) option. This option puts a GREATER THAN sign in front of the displayed keyins.

---

@STSTAR

This processor runs as a background run to provide the ST* keyin. The ST* keyin is a variant of the ST keyin for sites with Security Option 1 (or above). In this environment, operators must specify an account and user-id on ST keyins; this is a major inconvenience. This processor reads a set of RUN$ files (which can include site-defined RUN$ files as well as standard Unisys RUN$ files) and registers for the ST* keyin via ER KEYIN$. When an ST* keyin is received, this processor searches each RUN$ file in turn. When it find the element it starts it via either @START,/U or by sending a message to Smart Console asking that it do an ST keyin. Here is sample background run ECL that uses one Unisys RUN$ file and two local (site-created) RUN$ files (the backslash, U option and period-ampersand are required):

   
      @RUN       STSTAR,blah,blah   
      @STSTAR,R                              . R = real-time
      \START,/U  SYS$LIB$*RUN$PROD.&
      \ST        SYS$LIB$*RUN$TEST.&
      \ST        SYS$LIB$*RUN$.&
      @EOF  

In this example, runs found in RUN$PROD will be started via @START,/U whereas runs found in RUN$TEST or RUN$ will be started by sending a message to Smart Console requesting that it perform an ST keyin.

Since this processor is not meant for demand users, the 'H' (help) option is not provided. Please read the comments at the top of this processor before using it.

---

@SWTIME

This MASM processor decodes a twelve-digit octal SWTIME or Modified SWTIME word.

---

@TDATE

This MASM processor decodes a twelve-digit octal TDATE$ word or DMS 1100 timestamp word into a readable form. This is very handy when looking at dumps. Note that TDATE$ timestamp will roll over on 2028-01-01.

---

@TWAIT

This MASM processor waits a given number of milliseconds and then exits. It's very useful when a batch job must wait a while to allow something else to finish before continuing.

---

@UDMDEL

This MASM processor is the UnDeliverable Message DELete routine. It will eat undeliverable output messages to free up queue items. It uses the CMS interface to MCB in order to read and ACK each of the messages queued to a given PID. As a result, it has to run as a CMS. You must configure the tag CMSNUM to a CMS number not used by any other CMS, MCB, MAPPER, etc. on your system! There are other site-specific config tags in the program (locate the heading SITE CONFIGURATION TAGS). In addition, you must change the map to point it at your MCB. The map looks a little bizarre as a result of needing to keep the DBANK based on the utility I-BDR. This routine uses subroutine GETMCBBDI, which you must also configure for your site (see above). To execute this you must be capable of Executive Requests RT$, CMS$REG, and RT$PID; and you must be allowed the real-time level configured. When you execute the processor, it must assign the PID. Thus, the PID must be down to all other CMS programs. The default absolute is configured for Application Group 7. This is one of those programs that can save you from an outage, but it's strong medicine. So be careful!

---

@UPDIR

This processor performs the UPDIR$ function of ER MSCON$ to ask the Exec to update the MFD for a file, rather than waiting for the file to be @FREEd. This forces the Exec to record any DAD (Device Area Descriptor) table expansion, which might otherwise be lost should the system fail. It's particularly useful for UDS sites that leave files assigned to a Common Name Section. This processor works on Exec 43R6 (SB4R6) or above. Please carefully read the comments at the top of this program before using it.

C Processors

@DIFF

This C processor is our version of the standard Unix diff utility. We took @DIFF from the Unisys Release Tape (UPLI package #1097) and made it somewhat more 2200-friendly (for example, our version displays facility reject status codes). There is more work to be done to make this follow all 2200 processor conventions. And a serious restriction remains: @DIFF cannot read some elements, in particular many elements with element back-cycle lines (i.e., elements whose element cycle is not zero). @DIFF reads elements via standard C libraries (e.g., 'fget'). We have yet not determined whether the problems are in @DIFF or the Unisys implementation of these libraries.

---

@RUNPL

This C processor pipes info about active runs, including TIP transactions.

---

@SHA1PL

This C processor uses pipes an SHA-1 hash of a sequential SDF file. It is a port of a freeware C implementation to the 2200. You will find this to be slow on large files. Unisys provides secure hash functions and much more in their CIPHER-API product, which will be more suitable for many sites.

---

@TAG

This C processor reads or sets a file's site use (MUSER$) cell in the MFD. You can later use FAS to select files with a given site use cell value. This is a C version of @MUSER. It is written in UCS C using SLIB, so you must be on System Base 4 (or above). Note that this processor is @LINKed and is a Zero-Overhead Object Module (ZOOM). Its construction is described in Writing Processors in C, UNISPHERE, August/September 1993.

UCS COBOL (UCOB) Processors

@UTCPL

This UCOB processor pipes UTC (Coordinated Universal Time).

ASCII Fortran (FTN) Processors

@SECDMP

This ASCII Fortran processor dumps sector-addressable disk files. It will also interpret DMS page headers and DARP page zero. The world doesn't need another dumper, but SJM wrote this as part of a training course to try to show his students how fun and easy this kind of programming is. The DMS functionality is easier to use than the DMU. You'll need ASCII Fortran installed at your site, because this was collected with common banked ASCII Fortran libraries.

Generic Processors

If you wish to use a file other than SYS$LIB$*LOCALRS, then you must change the ADDFILE tag in GENERIC, re-assemble and re-collect GENERIC, and copy GENERIC as the processors named below. Then you must edit the '/ADD', '/SKEL' and '/SGS' elements to specify your new files and then copy the elements to your file.

---

@COMERR (used with COMAPI/ADD, COMAPI/SKEL and COMAPI-ERROR/SGS)

This generic processor displays the English description of COMAPI errors. We'd much appreciate corrections or updates to the text.

---

@COPYG (used with COPYG/ADD, COPYG/SKEL1 and COPYG/SKEL2)

This generic processor generates FURPUR @COPY,G commands that copy a set of files to or from tape. When copying to tape it writes a special file of SGSs as the first file of the tape, followed by the user-specified files. The SGSs describe the files that follow on the tape. When copying from tape to disk this file of SGSs is used to reconstruct the files on disk (optionally changing the qualifier or ignoring file cycle information). The purpose of this processor is to provide a method of using COPY,G to create tapes without having to remember the order of the files on the tape. This processor requires @MFDPL.

---

@CYC (used with CYC/ADD and CYC/SKEL)

This generic processor displays information about what f-cycles of a file exist. It provides a better display than the FURPUR @CYCLE command. @CYC is a good example of pipelining and generic processing. It gets its MFD data from @MFDPL.

---

@DAD (used with DAD/ADD and DAD/SKEL)

This generic processor displays information about Device Area Descriptors for catalogued disk and memory files. It does not support temporary files or tape files. It uses pipelined data from @DISKPL and @MFDPL

---

@DISK (used with DISK/ADD and DISK/SKEL)

This generic processor displays information about your disk drives. It gets its disk drive data from @DISKPL.

---

@LC (used with LC/ADD and LC/SKEL)

This generic processor locates all occurrences of a string within a given program file. It uses @ZIP to read and search elements.

---

@MCBERR (used with MCBERR/ADD, MCBERR/SKEL and MCBERR/SGS)

This generic processor displays the English description of Message Control Bank (MCB) error codes, abort codes, function codes, as well Step Control ER status codes. The English text is in element MCBERR/SGS. We'd much appreciate any corrections or updates.

---

@MQFERR (used with MQFERR/ADD, MQFERR/SKEL and MQFERR/SGS)

This generic processor displays the English description of ER MQF$ error codes. We'd much appreciate any corrections or updates.

---

@PCT (used with PCT/ADD and PCT/SKEL)

This generic processor displays various information about your run from the Program Control Table. Optionally, it will show your security profile (for sites with Security Option 1 or above). PCT is sensitive to the Exec level it runs on. This version shows nanosecond SUPs (available from Exec 44R3 and higher). It also has a slightly different display than older versions. This version is fully functional for Exec 44R3 and higher. For lower Exec levels, it displays SUPs as zero. It uses data piped by @PCTPL.

---

@PRTF (used with PRTF/ADD and PRTF/SKEL)

This generic processor provides a more detailed display than does @PRT,F. It relies on @MFDPL to pipe MFD information. It replaces the MASM @PRTF.

---

@QC (used with QC/ADD and QC/SKEL)

This generic processor copies the files on a symbiont queue (or optionally for a run-id) to elements of a target program file. The print files remain unchanged on the symbiont queue. This is meant for demand use and will only handle the first 169 entries. It uses @QPIPE. to read symbiont queues.

---

@QITEM (used with QITEM/ADD, QITEM/SKEL1 and QITEM/SKEL2)

This generic processor displays the piped output of @RDSCQ in a more readable form.

---

@SELECT (used with SELECT/ADD and SELECT/SKEL)

This generic processor is a front-end for @FASPL. You need to have built @FASPL with the FAS local code provided (see next section). SELECT/SKEL assumes that you've installed @FASPL. Here's how you could pipe the names of all files with qualifier SJM that were catalogued more than ten days ago:

   
    @SELECT 
    QUAL = 'SJM'  AND  CAT_AGE > 10 

You could then use @GENER8 or your own SSG skeleton to process the selected filenames.

---

@SYS (used with SYS/ADD and SYS/SKEL)

This generic processor displays system information such as site-id, machine type, Exec level and build-id, most recent boot type and time, etc. It optionally displays the EXERR History Table. It uses data piped by @MCTPL.

---

@T (used with T/ADD and T/SKEL)

This generic processor displays a subset of run information shown by the T keyin. It allows selection by run type, run-id, account and program name. It displays one run per line. It uses data piped by @MCTPL.

---

@TOCOMP (used with TOCOMP/ADD and TOCOMP/SKEL)

This generic processor compares the table-of-contents of two program files. It's useful for determining what elements have been added, changed or deleted between two versions of a software system. It compares element names, types, and date/time. It does not look at the contents of elements. @TOCOMP provides a much better display format than '@DOWN,D'.

---

@TOUCH (used with TOUCH/ADD and TOUCH/SKEL)

This generic processor updates (but does not change content) all symbolic elements in a given files. It uses @IPF OLD and REPL commands to do this.

---

@UTC (used with UTC/ADD and UTC/SKEL)

This generic processor shows UTC (Coordinated Universal Time). It uses @UTCPL.

---

@Z (used with Z/ADD and Z/SKEL)

This generic processor provides a shortcut into @ZIP. It's only useful for sites that have installed @ZIP. Sample calls:

   
    @Z    file.elt          . show first 20 lines of file.elt   
    @Z,B  file.elt          . show last  20 lines of file.elt   
    @Z,B  file.elt,,10      . show last  10 lines of file.elt   
    @Z    file.elt,STEVE,9  . locate 9 occurences of 'STEVE' in file.elt
    @Z,F  file.elt,STEVE    . find   1 occurence  of 'STEVE' in file.elt

UCOB Programs

SDFPRINTUTIL

This UCOB program uses SLIB to read multiple input SDF print files and write the records to a single output file that is either an SDF print file, an IBM (EBCDIC) print tape, or an SDF data file with IBM-style carriage control. The SDF carriage control is always replicated in the output file. See the comments at the top of the program for more information.

Batch Jobs

QCOPY

This sample job uses @QPIPE, @QDEL and FURPUR to copy print files from a symbiont queue to elements in a program file, deleting the print files after copying them. (We probably should have called it QMOVE, but it's too late now.) It can handle more than 169 entries in the queue. This job uses QCOPY/SKEL.

SSG Skeletons

QCOPY/SKEL

This skeleton is used by the QCOPY sample batch job. Its generates ECL to move print files from a symbiont queue to elements in a program file. QCOPY expects to find this skeleton in the file SYS$LIB$*LOCALRS.

Local Code for FAS: @FASPL

Use the resultant FAS absolute under another name (e.g., @FASPL) solely for piping the filenames generated by the LIST command. Always execute the pipelining version of FAS with the 'P' option. Continue to use the real FAS for important backup and recovery work! For a discussion of pipelining in general and the pipelining version of FAS in particular, see Simulating Unix Pipelines, UNISPHERE, March 1993.

A New Feature Suggestion to add pipelining logic to FAS was rejected. See UCF #43082981.

MSAR 5R1 (and above) implements a similar feature. Since it is a supported product, we strongly recommend it over FASPL. We continue to provide the FASPL local code for those without access to MSAR.

Here is an example of how to use our pipelining version of FAS:

   
    @ . Delete back up information for destroyed tape TAPE22 ...
    @FASPL,P
    LIST CRITERIA = [ VOL = 'TAPE22' ]; ACT;
    @SSG   ,PL$$FASPL.  
    SKEL
    *COPY  SYS$LIB$*LOCALRS.SETUP-FIELDS
    *INCREMENT F TO [FILE]  
    #DBACK  [FILE,F,FILE_QUAL,1]*[FILE,F,FILE_NAME,1]([FILE,F,FILE_CYC,1]). 
    *LOOP . F   
    @EOF
    @EOF

This accomplishes the same thing using @SELECT and @GENER8 to save coding:

   
    @ . Delete back up information for destroyed tape TAPE22 ...
    @SELECT 
    VOL = 'TAPE22'  
    @GENER8 
    #DBACK  [*QFC]. 
    @EOF
    @ADD   ECL  

FAS-FIX/3R3E

This is the local code for FAS 3R3E.

FAS-FIX/4R1A

This is the local code for FAS 4R1A.

FAS-FIX/5R2

This is the local code for FAS 5R2 (SB5R4). This fix has additional functionality: the date and time of the most recent FAS backup is also piped.

FAS-FIX/7R1

This is the local code for FAS 7R1 (SB7). This fix has the same functionality as FAS-FIX/5R2.

FAS-FIX/8R1

This is the local code for FAS 8R1 (HMP-IX 7.0). This fix has the same functionality as FAS-FIX/5R2.

FAS-FIX/9R1

This is the local code for FAS 9R1 (CP-OS-2200 9.0). This fix has the same functionality as FAS-FIX/5R2.

FAS-FIX/10R1A

This is the local code for FAS 10R1A (CP-OS-2200 11.0). This fix has the same functionality as FAS-FIX/5R2.

FAS-FIX/10R4

This is the local code for FAS 10R4 (CP-OS-2200 12.0). This fix has the same functionality as FAS-FIX/5R2.

FAS-FIX/10R5A

This is the local code for FAS 10R5A (CP-OS-2200 13.1). This fix has the same functionality as FAS-FIX/5R2.

FAS-FIX/10R6

This is the local code for FAS 10R6 (CP-OS-2200 14.0). This fix has the same functionality as FAS-FIX/5R2.

FAS-FIX/11R1

This is the local code for FAS 11R1 (CP-OS-2200 15.0). This fix has the same functionality as FAS-FIX/5R2.

FAS-FIX/12R1

This is the local code for FAS 12R1 (CP-OS-2200 17.0). This fix has the same functionality as FAS-FIX/5R2.

Re-compiling Modules

1. Examine the ASGUSE element. This provides @USE names for the files containing source, relocatables, absolutes, etc. The default version assumes they're in a file called GROUPW*TOOLSET. Change this as necessary. If you don't have ASCII Fortran (FTN) installed, drop the @USE name for it.
2. @ADD your ASGUSE element.
3. @ADD the '/ECL' element for each routine you wish to re-compile. Remember to do procs first, then subroutines, then mainlines. Also remember to breakpoint if you're doing this in demand.

Here is an example of how you could re-compile the MCBGETBDI subroutine and the processors that use it in demand:

   
        @ADD  GROUPW*TOOLSET.ASGUSE 
        @BK1                               . or equivalent  
        @ADD  ECL$.GETMCBBDI/ECL
        @ADD  ECL$.PASOFF/ECL   
        @ADD  ECL$.PIDSTA/ECL   
        @ADD  ECL$.UDMDEL/ECL   
        @BK2,E                             . or equivalent  

If you wish to re-compile everything, you can @ADD the element COMPILE/ALL. If you don't have ASCII Fortran (FTN), UCS COBOL (UCOB) and/or UCS C (UC) installed, drop programs written in those languages from COMPILE/ALL (the comments will help you).
4. When checking the compiles, you should see only 'U' (undefined) flags for MASM, and no @MAP or @LINK errors.

Installing the Processors

If you use any of the generic processors, you must catalog a file called SYS$LIB$*LOCALRS and copy elements used by these processors and their SSG skeletons into it. The INSTALL/LOCALRS element will copy all appropriate symbolic elements from the file with @USE name ECL$ (normally GROUPW*TOOLSET) to the file with @USE name LOCALRS$ (normally SYS$LIB$*LOCALRS).

Future Directions

The members of Group W are very mature. Two of use have retired.

Future versions of SJM's software will rely more on SSG and less on MASM programs that read proprietary Exec data structures. Maintenance of programs that "know where things are" in the MFD, PCT, or MCT is tedious, time-consuming, and difficult to test, so no more than one program should read each data structure.

Here are the most likely future changes (none are guaranteed):

• Fix the @FREEA bug whereby it will go into an endless loop when it tries to @FREE the +1 cycle of a temporary file.
• @PCTPL may pipe additional fields (e.g., the privilege and ER masks).
• Generic processors may rely on a parameter in SYS$LIB$*LOCALRS.GWTS-CONFIG/SGS to determine at run-time whether they are available to batch runs. Sites might wish to restrict some programs to demand runs only so that they won't get into production jobs.
• The site-standard date display parameters in SYS$LIB$*LOCALRS.GWTS-CONFIG/SGS may be expanded to allow customization by user-id.
• @DIFF may be enhanced to be able to read all input elements.
• Although some fixes have been made, @MFDPL does not handle f-cycles well. Its f-cycle processing should be re-written.
• @MFDPL may be enhanced to optionally pipe the entire MFD.
• @MFDPL may be enhanced to pipe XPC caching information and @PRTF would display it.
• We have too many symbiont processors (@Q, @QC, @QCNT, @QDEL, @QDISP, @QPIPE), all written in MASM. Combining the MASM processors into one and supporting it with several generic processors is desirable. This is low on our list of priorities.
• @DMSERR may be converted to a generic processor.
• SJM plans to drop some of his less useful utilities.