Group W Toolset Documentation

Welcome to the Group W Toolset (GWTS) for Unisys 1100/2200/Dorado computers. This is version 5.1 released on 2014-01-17.

Table of Contents

Disclaimer and License

Please carefully read the following disclaimer. Your use of the programs in this package will indicate your acceptance of the terms and conditions described here.

   
              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)

In "Alice's Restaurant" the Group W bench was where the U.S. Army recruiting office made you sit "if you may not be moral enough to join the Army after committing your special crime." Well, it's also where they might send you if you like writing assembly language utilities and then giving them away! The contents of this package are our "shovels and rakes and implements of destruction."

Group W is three Unisys 1100/2200 systems programmers who worked together for several 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 as follows:

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

       Tom Nelson (aka THN)            tom.nelson atsign ca.unisys.com  

       Bill Toner (aka WJT)            william.toner atsign ca.unisys.com   

Advantages of This Package

We think the Group W Toolset has several advantages over most other 2200 freeware:

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) 13.1. 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
We provide source code 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 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

8. 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.  @CYCLE  GROUPW*TOOLSET.,0   

    5.  @CAT,P  GROUPW*TOOLSET.,F///2000

    6.  @ASG,AX GROUPW*TOOLSET. 

    7.  @ADD your2200file.  

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

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

10. Other Free Software We Recommend
As the number of 2200 sites diminishes, there is less available free software:

Release Matrices

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

GWTS Release Date of Release
1.0 1992-11-??
1.1 1993-10-28
1.2 1993-11-06
1.3 1994-02-07
1.4 1994-02-14
1.5 1994-03-29
1.6 1994-05-20
2.0 1994-06-10
2.1 1994-07-02
2.2 1994-08-04
2.3 1994-09-07
2.4 1994-11-05
2.5 1995-03-20
2.6 1995-05-16
2.7 1995-06-28
3.0 1995-07-12
3.1 1995-11-26
3.2 1996-01-10
3.3 1996-07-04
3.4 1996-09-02
3.5 1996-11-14
4.0 1997-07-03
4.1 1997-12-11
4.2 1998-07-07
4.3 1999-10-11
4.4 2001-07-21
4.4a 2001-09-01
4.5 2002-12-09
4.6 2004-05-30
5.0 2011-08-19
5.1 2014-01-17

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

Program Name Group W Toolset Release Level
3.0 3.1 3.2 3.3 3.4 3.5 4.0 4.1 4.2 4.3 4.4 4.5 4.6 5.0 5.1
@AC 1R4B 1R4C 1R4C 1R4C 1R4C 1R4C 1R4C 1R4C 1R4D 1R4D 1R4D 1R4D 1R4D 1R4E 1R4E
@ASGCNT 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A
@COPYG 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B
@CYC 1R2 1R2 1R2 1R2 1R2 1R4 2R1 2R1 2R1 2R1A 2R1A 2R1A 2R1A 2R1B 2R1B
@DAD 1R1B 1R1B 1R1B 1R1B 1R1B 1R1C 1R1D 1R1D 1R1D 1R1D 1R1D 1R1D 1R1D 1R1D 1R1D
@DBACK 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2
@DIFF




1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1A 1R1A
@DISK 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R2 1R2 1R2 1R2 1R4 1R4 1R4 2R1 2R1
@DISKPL 1R1A 1R1A 1R1A 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1C 1R1C 1R1C 2R1 2R1
@DMSERR 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2B
@EACQ 2R1C 2R1C 2R1C 2R1C 2R1C 2R1C 2R1D 2R1D 2R1D 2R1D 2R1D 2R1D 2R1D 2R1D 2R1D
@FASPL 4R1A 5R2 5R2 5R2 5R2 5R2 5R2 5R2 7R1 7R1 7R1 8R1 8R1 10R4 10R4
@FREEA 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2
@GENER8 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A
GENERIC 3.0 5.0 5.0 5.0 5.0 5.0 6.0 6.0 6.0 6.1 6.1 6.1 6.1 6.1 6.1
@I 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B 1R5B
@KEYIN 1R2D 1R2D 1R2D 1R2D 1R2D 1R2D 1R2D 1R2D 1R2D 1R2D 1R2D 1R2D 2R1 2R1 2R1
@LC












1R1 2R1A
@MANGLE 2R1B 2R1B 2R1B 2R1B 2R1B 2R1B 2R1D 2R1D 2R1D 2R1D 2R1D 2R1D 2R1D 2R1D 2R1D
@MCBERR 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B
@MCTPL





1R1 1R1 1R1 1R2A 1R3 1R4A 1R4A 1R4A 1R4A
@MFDPL 1R1A 1R2A 1R2A 1R2A 1R2A 1R2A 2R1 2R2 2R2A 2R2A 2R2C 2R4 2R4 2R4 2R4
@MQFERR 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B
@MUSER 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C 2R2C
@PASOFF 1R2 1R2 1R2 1R3 1R3 1R3C 1R3C 1R3C 1R3C 1R3C 1R3C 1R3C 1R3C 1R3C 1R3C
@PCT
(MASM)
3R2B 3R2B 3R2B 4R1 4R1 4R1 4R1A 4R1A 4R1B 4R1B 4R2 4R2 4R2

@PCT
(SSG)











5R1 5R1 5R1 5R2
@PCTPL






1R1 1R1 1R1 1R2A 1R2A 1R2A 1R2A 1R3
@PIDSTA 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1B 1R1B 1R1B 1R1B 1R3
PIPELINE 2.0 2.0 2.0 2.1 2.1 2.2 2.3 2.3 2.3 2.3 2.3 2.3 2.3 2.3 2.3
@PRTF ? 1R2F 1R2F 1R2F 1R2F 1R2F 2R1 2R1 2R1 2R1B 2R1B 2R2 2R2 2R2 2R2
@PSWCHG









1R1 1R1 1R1 1R1 1R1
@Q 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B 2R6B
@QC 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R2 1R2 1R2 1R2 1R2 1R3 1R3 2R1 2R1A
QCOPY/SKEL 2R1B 2R1B 2R1B 2R1C 2R1C 2R1C 2R1C 2R1C 2R1C 2R1C 2R1C 2R1C 2R1C 2R1C 2R1C
@QDEL 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 2R1 2R1
@QDISP 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A 1R4A
@QITEM 1R1 1R1 1R1 1R1 1R1 1R1 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A
@QPIPE 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R1A 2R2 2R2
@RDSCQ 1R1 1R1 1R1 1R1 1R1 1R1 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A 1R1A
@RDMPPX 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1
RUNINFO 4.0 4.1 4.1 5.0 5.0 5.0 5.1 5.1 5.2 5.2 5.3 5.3 5.3 5.3 5.4
@RUNPL









1R2 1R2 1R2 1R4 1R4
SDFPRINTUTIL




1.0 1.0a 1.0a 1.0a 1.0a 2.0 2.0a 2.0a 2.0a 2.0a
@SECDMP 1R2 1R2A 1R2A 1R2A 1R2A 1R2A 1R2A 1R2A 1R2A 1R2A 1R2A 1R2A 1R2B 1R2B 1R2C
@SELECT ? 3R1A 3R1A 3R1A 3R1A 3R1B 3R1C 3R1C 3R1C 3R1C 3R1C 3R1E 3R1E 3R1F 3R1F
@SHA1PL












1R2 1R2
@SIPSTA 1R4 1R4 1R4 1R4 1R4 1R4 1R4 1R4 1R4 1R4 1R4 1R4 1R4 1R4 1R4
@SPY 2R3 2R3 2R3 2R3 2R3 2R3 2R3 2R3 2R3 2R3 2R3 2R3 2R4 2R4 2R4
@STSTAR 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 2R1 3R1A 3R1C 3R1C 3R1C 3R1C 3R1C
@SYS





1R1 1R1 1R1 1R1 1R2 1R3A 1R3A 1R3B 1R3B
@SYSID 2R4A 2R4A 2R4A 2R4A 2R4A 2R4A 2R5 2R5 2R5A 2R5B 2R5B 2R5C 2R5C

@T












1R2 2R1
@TAG 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1 1R1
@TDATE 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R3 1R3 1R3 1R3 1R3 1R3 1R3
@TOCOMP





1R2 1R2 1R3A 1R3A 1R3A 1R3A 1R3A 1R3B 1R3B
@TOUCH












1R1 1R1A
@TWAIT 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2 1R2
@UDMDEL


1R2B 1R2B 1R2B 1R2B 1R2B 1R2B 1R2C 1R2C 2R1 2R1 2R1 2R1
@UPDIR 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B 1R1B
@Z 2R1 2R1 2R1 2R2 2R2A 2R2A 2R2B 2R2B 2R2B 2R2B 2R2B 2R2B 2R2B 3R3 3R4

Contents of the Distribution File

We assume you've copied this file to a catalogued disk file called GROUPW*TOOLSET. If not, please update all occurrences of string 'GROUPW*TOOLSET' in element ASGUSE.


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. You may change this if you wish.


GWTS-CONFIG/SGS
This element contains SGSs that provide site-defined configuration data for all SSG procs and generic processors. 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.


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-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. 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). Since you must configure this routine for your site, we don't provide a default relocatable.


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.


@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. No default absolute is included for this processor because you must configure subroutine GETMCBBDI and then re-assemble the subroutine and then this processor.


@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. No default absolute is included for this processor because you must configure subroutine GETMCBBDI and then re-assemble the subroutine and then this processor. We leave it to you to develop downstream uses for this pipeline, based on what your site needs.


@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.


@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:


@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.


@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.


@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. Because you must configure @UDMDEL for your site/application, no default absolute is provided. 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

A generic processor is one or more SSG skeletons front-ended by a MASM processor (GENERIC). Thus, all generic processors use the same absolute (GENERIC) renamed. Each generic processor has an @ADD element called 'xxxxxx/ADD' (where xxxxxx is the processor name). Some also use an SSG skeleton called 'xxxxxx/SKEL' and Stream Generation Statements (SGSs) called 'xxxxxx/SGS'. You must place the '/ADD', '/SKEL' and '/SGS' elements in SYS$LIB$*LOCALRS.

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.

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

This local code allows you to build a pipelining version of FAS. The fixes are in COMUS batch input format. To create a pipelining version of FAS, re-build FAS with the appropriate fix. The local code expects that relocatable PIPELINE is in file GROUPW*TOOLSET. The collection of the 'FAS' absolute should be error-free. (The collection of the FASLIB$ absolute will have errors, but this is not a concern.)

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  
See also @SELECT and @GENER8.
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.

Re-compiling Modules

If you need to re-compile any of these programs, do the following:
  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.
  4. 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).

  5. When checking the compiles, you should see only 'U' (undefined) flags for MASM, and no @MAP or @LINK errors.

Installing the Processors

You choose the file(s) into which you wish to install processor absolutes. You can locally install them with SOLAR, or simply copy them to a user file.

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 Group W Toolset is fairly mature. Large-scale additions or enhancements are not anticipated, but some refinements and enhancements are likely.

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):

*EOF*