The Rutherford Appleton Program Library has been classified into groups of subroutines which are numbered within each class. A list of titles is given here together with an entry point index and a keyword-in-context index. This section of the manual is updated from time to time and an up-to-date copy is kept in CMS in the file named TITLES LISTING on the minidisk USDOC 194 (no password needed).
A complete set of program abstracts is given following this section. All of the writeups, excluding those in the utilities section, are also available in CMS, either via the help system, the find system, or in lineprinter form on USDOC 194. For example, the command HELP RHELIB SPM will access the online writeup for the routines SPM and GPM (SY/9 and SY/10), whilst the file SPM LISTING on USDOC 194 contains a copy of the same writeup in a form suitable for output on a lineprinter.
FIND SPM will also find this lineprinter copy. The FIND command can also be used to do a keyword search eg. FIND SORT.
Missing numbers, such as DH/7, are for earlier routines that are no longer needed.
AL/1 MTINV4 Inversion of a real symmetric matrix AL/2 MTINV8 AL/3 MTREC4 Inversion of a general real matrix AL/4 MTREC8 AL/5 SYMIN4 Inversion of a positive definite symmetric matrix AL/6 SYMIN8 AL/7 SOLVE4 Simultaneous equations and least squares fitting AL/8 SOLVE8 AL/9 HOUSE4 Solution of simultaneous equations and least square fitting by Householder transformations AL/10 HOUSE8 AL/11 MC03AS Efficient scalar product routines AL/12 SSPS AL/13 MC03AD AL/14 DSPS AL/15 MC03AP AL/16 DSPP AL/17 MC03AQ AL/18 DSPD AL/19 SMMS Fast accurate matrix multiplication AL/20 DMMS AL/21 DMMD DH/3 SSORT Sorting of character strings DH/4 ASORT Arithmetic sorting of numbers DH/5 DSORT DH/6 ISORT DH/9 SLL Shift operations ignoring overspill DH/10 SRL DH/11 SLLS Shift operations storing overspill DH/12 SRLS DH/13 PACKER Routines for integer storage economy DH/24 CRACK Scaling a number into the range 0.5 to 1.0 DH/26 UNBIT4 Unpacking and repacking of bit strings DH/27 REBIT4 DH/28 UNBIT1 DH/29 REBIT1 DH/31 TRCONV General purpose translation package DH/32 TRLOAD DH/33 TRDELE DH/34 TR$SET DH/35 USWOP1 Interchanging the contents of two arrays DH/36 ICOMPR Comparing two byte strings DH/48 USETB Bit manipulation operations on arrays DH/49 UCLRB DH/50 UFLIPB FN/4 PB01AS Evaluation of a real polynomial FN/5 IRAND Random number generator FN/11 DBJ0 Bessel functions FN/12 DBJ1 FN/13 DBY0 FN/14 DBY1 FN/15 DBI0 FN/16 DBI1 FN/17 DBK0 FN/18 DBK1 FN/19 BINOM Compute a binomial coefficient FN/20 DJMN An element of a rotation matrix FN/21 PNM Legendre polynomials FN/22 CGCOEF Clebsch-Gordan coefficient FN/23 ABC Clebsch-Gordan coefficient (special case) FN/24 DELTA The triangular function FN/25 FACT The factorial function FN/26 RACAHW The Racah W-coefficient FN/27 RACAHX The Racah X-coefficient FN/28 RACAHZ The Racah Z-coefficient GR/1 CONTRO ENPLOT compatibility GR/2 ENPLOT Histogram and scatter plot production RW/10 EXCPIN Routine for reading non-standard tapes SY/1 MAINCS Dynamic access to main core storage SY/2 LCS SY/3 KCS SY/4 CLOCK Time and date SY/7 KLOCK Time of day SY/8 DATE The date SY/9 SPM Masking arithmetic interruptions SY/10 GPM SY/11 TLABEL Serial number of tape or disk SY/14 DEFINU Define Fortran direct access data set SY/16 CPULFT Measurement of CPU time SY/17 LINK Calling one program from another SY/18 SETIME CPU time interruption SY/19 PARMST Improved access to parm information SY/20 DSNAME Obtain name of data set SY/21 GETDD DDname from stream number or characters SY/22 DSETUP Auxiliary control blocks SY/23 IDVICE Device type information SY/24 SETDSN Reset dsname parameter SY/25 SERLAB Reset volume / file / label / dsname SY/27 CLOSET Close a data set SY/28 TFILAB Obtain volume and file number of tape SY/29 CHJFCB Change reference to PDS SY/30 DSPMOD Reset DISP parameter to MOD SY/31 ENQ Control use of resources between programs SY/32 DEQ SY/41 STIMER Timed wait interrupts SY/44 IDUNIT Obtain OS address number SY/45 JPNAME Job and program names SY/46 STOP Issue stop code SY/47 BLKCNT Obtain tape block count, block size and density SY/48 MVSID Machine identification SY/49 INDUSE CMS resource usage SY/50 USERID Userid of an MVS job SY/51 TDMSWU Last write information from TDMS for a tape SY/52 TDMSRU Last read information from TDMS for a tape SY/53 TDMSDU deletes a user record from the TDMS database. SY/54 TDMSPU writes a user record into the TDMS database. SY/55 TDMSGU reads a user record from the TDMS database. SY/56 TDMSDC deletes a comment record from the TDMS database. SY/57 TDMSPC writes a comment record into the TDMS database. SY/58 TDMSGC reads a comment record from the TDMS database. SY/59 GETACT Accounting fields from MVS job card SY/60 GETSAM Interrogate the MVS accounts database SY/61 GETAUS Interrogating the SAM database in MVS SY/62 DEOVER Program mask exception test and set subroutines SY/63 FPOVER SY/64 SIGNIF SY/65 QXFLO SY/66 QFPOVE SY/67 SIGNI SY/68 QDEOVE SY/69 SYSREQ Inter-System Service Request Facility SY/70 ACCT Interface to Cross-System Accounting************************The original copies dating back to 1976 could not be OCR'd successfully*****************
UT/1 DITTOD Dump part of a disk file to the lineprinter UT/2 TPCOPY Copy a tape to another labelled or unlabelled tape. UT/3 XTAPE List file names on a tape and format of the files. UT/4 CCOPY Copy all or part of a source file from tape or disc to another tape or disk with or without code conversion UT/5 CLIST Copy a source file from tape or disk to or disk. UT/6 LISTLIB List members of a PDS or library. UT/6 LISTARCH List archived members of a library. UT/6 ARCHIVE Archive a member of a library. UT/6 RETRIEVE Retrieve a member of a library. UT/6 RENAME Rename a member of a PDS or library. UT/6 REMOVE Remove a member of a PDS or library. UT/7 ERASE Delete a data set. UT/8 LPDS List the members of a PDS. UT/9 RLDISK List the data sets on a disk. UT/10 LVTOC List the data sets on a disk. UT/11 RLDUMP Backup disk to tape. UT/12 DDUMP Dump part of a disk file to lineprinter in character or hexadecimal. UT/13 DITTODSK Dump part of a disk file to lineprinter in character or hexadecimal. UT/14 GCARADOC Document a Fortran Program. UT/15 ERTREE Draw tree structure of an overlay program. UT/16 GCNEAT Tidy up a Fortran program. UT/17 GENER Copy a single data set to tape or disk. UT/18 IEBGENER Copy or list any data set. UT/19 IEBCOPY Copy all or part of a PDS. UT/20 CDCTAPE Read a CDC (60 bit word) tape with mixed real and integers in binary code. UT/21 COMPARE Compare two data sets. UT/22 CONVERT Convert a data set from one character code to another. UT/23 DSDUMP Formatted dump of a data set. UT/24 DSCLEAR Clear a data set. UT/25 DSFREE Free unused space in a data set. UT/26 DSRLSE Release unused extents from a data set. UT/27 GENLIST For use with IEHLIST. UT/28 EDIT The Rutherford/Warwick/Cambridge editor. IE An alternative name for EDIT. UT/29 ROFF Offline layout facility. UT/31 FLIST List to the FR80. UT/32 SELECT Selective copy of a data set. UT/33 EDITLIB Create autocall library from single object deck, UT/34 VSCOPY VS version of IEBCOPY. UT/35 TAPEANAL Analyse the files on a tape.
The Single Precision version is used as follows:
CALL MTINV4 (A, NA, N)
This will invert the N row symmetric matrix which is stored in the two-dimensional array A. A must be declared as having dimensions (NA,MA) where neither NA nor MA may be less than N. The element ij of the matrix should be stored in A(I,J) for I=1,N and J=1,N. The matrix A will be replaced by its inverse.
The Double Precision version is used as follows:
CALL MTINV8(A, NA, N)
but now A has to be declared as a REAL*8 array.
To improve the stability, maximum pivots are sought at each stage of the numerical process.
The routines fail if N > NA or if N > 128, or if A is a Singular Matrix.
IBM 360 Assembler.
MTINV4 and MTINV8 are separate subroutines with three arguments each. The second and third arguments must be Integer, and the first must be Real*4 and Real*8 respectively. No subsidiary routines are required.
MTINV4 and MTINV8 are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
R Taylor.
The Single Precision version is used as follows:
CALL MTINV4 (A, NA, N)
This will invert the N row symmetric matrix which is stored in the two-dimensional array A. A must be declared as having dimensions (NA,MA) where neither NA nor MA may be less than N. The element ij of the matrix should be stored in A(I,J) for I=1,N and J=1,N. The matrix A will be replaced by its inverse.
The Double Precision version is used as follows:
CALL MTINV6 (A, NA, N)
but now A has to be declared as a REAL*8 array.
To improve the stability, maximum pivots are sought at each stage of the numerical process.
The routines fail if N > NA or if N > 128, or if A is a Singular Matrix.
IBM 360 Assembler.
MTREC4 and MTREC8 are separate subroutines with three arguments each. The second and third arguments must be Integer, and the first must be Real*4 and Real*8 respectively. No subsidiary routines are required.
MTREC4 and MTREC8 are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
R Taylor
The Single Precision version is used as follows:
CALL SYMIN4 (A, IA, N, W, K)
where N > 0, and IA is not less than N. A contains an N row matrix and must be dimensioned (IA,JA) where JA must also not be less than N. On return from SYMIN4, A will have been replaced by its inverse. W is a work array of length N. K is an Integer which is set to 0 when the inversion is successful, or to 1 if the inversion fails.
The Double Precision version is used as follows:
CALL SYMIN8 (A, IA, N, W, K)
where A and W are now REAL*8 arrays.
The routines impose no upper limit on the value of N. The method of inversion is that of Cholesky decomposition and is extremely stable.
IBM 360 Assembler.
SYMIN4 and SYMIN8 are separate subroutines with five arguments each. The second and third and fifth arguments must be Integer, and the first and fourth must both be Real*4 and Real*8 for SYMIN4 and SYMIN8 respectively. No subsidiary routines are required.
SYMIN4/SYMIN8 are faster than MTINV4/MTINV8 and MTREC4/MTREC8 (by a factor of about 2) and faster than the Harwell inversion routines.
SYMIN4 and SYMIN8 are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
D W Dent
These routines will solve a set of N simultaneous equations A x = b with N unknowns where A is an N row matrix of coefficients. The method used is that of Gaussian elimination with partial pivoting. Subsequently, the solution of A x = c i.e. a new right hand side, can be accomplished economically by calling RESOL4 (or RESOL8).
The Single Precision version is used as follows:
CALL SOLVE4 (A, N, IA, B, X, WORK, K)
where A is a two dimensional array containing the coefficients and dimensioned (IA,JA), where neither IA nor JA are less than N, and N > 0. B is an array of N elements containing the right hand side of the equation. X is an array of N elements which will be used to store the solution. It is permitted for X and B to be the same array. WORK is an array of N half-words for internal use (to record row changes). The indicator K is set to zero when the equations have been solved successfully, or to 1 after a failure when the matrix is Singular or the input parameters are illegal. For SOLVE4 the arrays A, B and X are all single precision.
The Double Precision version is used as follows:
CALL SOLVE8 (A, N, IA, B, X, WORK, K)
where the arrays A, B and X are double precision, and the other arguments are as for SOLVE4.
The arrays A and B are modified by the routine, so if the second entry point RESOL4 (or RESOL8) is called, the matrix A must be left undisturbed and also the array WORK.
The secondary entry points have the same parameter list:
CALL RESOL4 (A, N, IA, B, X, WORK, K) CALL RESOL8 (A, N, IA, B, X, WORK, K)
Any number of different problems can be interleaved provided that separate storage arrays A and WORK are reserved for each problem.
E.g. Ax = b CALL SOLVE8 (A, N, IA, B, X, W, K) Cy = d CALL SOLVE8 (C, M, 1C, D, Y, WW, K) Ax = bb CALL RESOL8 (A, N, IA, BB, X, W, K)
There is no upper limit to N, but N must not be less than 2.
IBM 360 Assembler.
SOLVE4 and SOLVE8 are separate subroutines with seven arguments each. The second and third and seventh arguments must be Integer, and the sixth is at least Half-Integer, the remainder are Real*4 and Real*8 for SOLVE4 and SOLVE8 respectively. No subsidiary routines are required.
SOLVE4 and SOLVE8 are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
Note that RESOL4 and RESOL8 are only available from the Automatic Call Library with SOLVE4 and SOLVE8 respectively. It is not meaningful to use them in isolation.
D W Dent
These routines will solve a set of N simultaneous equations A x = b or provide a best-fit in the least squares sense to an over-determined set of M equations with N unknowns. Householder transformations are used to provide a very stable method.
The single precision version can be used with single precision data to give accuracy equivalent to that obtained by using a Gaussian elimination method with double precision data (e.g. subroutine SOLVES AL/8).
Secondary entry points REHOU4 and REHOU8 may be used to resolve the equations with a new right hand side, i.e. A y = c
The single precision version is used as follows:
CALL HOUSE4 (A, N, M, IA, B, X, K, WORK)
where A is a 2-dimensional array containing the coefficients and is dimensioned A(IA,JA) and neither M nor JA is less than N, and IA is not less than M. N must not be less than 2.
B is an M element array containing the right hand side of the equations. X is an N element array used to store the solution. X and B may be the same array. K is an indicator set to 0 when the solution is successful or to 1 otherwise. WORK is an array of length 2*N words used to record information for use by REHOU4. It may be omitted if you do not intend calling REHOU4. The arrays A, B, X and WORK are all single precision.
The Double Precision version is used as follows:
CALL HOUSE8 (A, N, M, IA, B, X, K, WORK)
where the arrays A, B, X and WORK are double precision, and the other arguments are as for HOUSE4.
The arrays A and B are modified by the routine, so if the second entry point REHOU4 (or REHOU8) is called, the matrix A must be left undisturbed and also the array WORK.
The secondary entry points have the same parameter list:
CALL REHOU4 (A, N, M, IA, B, X, K, WORK)
CALL REHOU8 (A, N, M, IA, B, X, K, WORK)
Any number of different problems can be interleaved provided that separate storage arrays A and WORK are reserved for each problem. This technique is further explained in the writeup of SOLVE4 and SOLVE8 (AL/7 and AL/8).
There is no upper limit to N, but N must not be less than 2.
IBM 360 Assembler.
HOUSE4 and HOUSE8 are separate subroutines with seven or eight arguments each. The second, third, fourth and seventh arguments must be Integer, and the remainder are Real*4 and Real*B for HOUSE4 and HOUSE8 respectively. The only subsidiary routine required is SQRT.
When used for the solution of simultaneous equations, these subroutines are a factor of 2 slower than SOLVE4 or SOLVE8. However, HOUSE4 can be used with single precision data to give accuracy equivalent to using SOLVE8 with double precision data. HOUSE8 can be used to give very accurate solutions to matrices which are nearly singular.
When used for least-squares fitting, the routines will give more accurate solutions in about the same time as the traditional Normal Equations method using SOLVE4 or SOLVE8.
HOUSE4 and HOUSE8 are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are both available in CMS. Note that REHOU4 and REHOU8 are only available from the Library with HOUSE4 and HOUSES respectively. It is not meaningful to use them in isolation.
D W Dent
A suite of routines are available for computing scalar products. These routines obtain greater accuracy through the extra precision of internal working, and extra speed through the ability of the 195 to perform two multiplications simultaneously.
The Functions (SSPS,DSPS,DSPP,DSPD) should be used when the scalar product only is required. The subroutines MC0SAx (note the zero is not the letter O) are particularly well suited to compute quantities such as A.B-X when the extra precision carries into the subtractions. Four modes of the subroutines make it possible to choose X+S, X-S, -X+S, or -X-S.
The various forms allow one to specify Single or Double Precision for input arguments, output arguments (or function values), and for the precision of internal working (note, however, that using quadruple internal precision is only half as fast).
(i) CALL MC03AS (A1, A2, B1, B2, X, RESULT, N, IFLAG)
MC03AD, MC03AP, MC03AQ have the same arguments, only their types differ.
(ii) Y = SSPS (A1, A2, B1, B2, N)
(iii) DOUBLE PRECISION DSPP, D, DA1, DA2, DB1, DB2
D = DSPP (DA1, DA2, DB1, DB2, N)
DSPD is called as DSPP. DSPS is as SSPS except DSPS must be declared as double precision (as should Y)
In all the above N is the number of terms in the product (if N<0 then S=0). The elements of the the input vectors must be uniformly spaced in computer memory locations. Al and A2 refer to the first and second elements of the first vector. B1 and B2 refer to the second vector. Thus one can treat rows or columns equally well. One can even go backwards e.g. (A(1), A(2), B(N), B(N-l), N, etc).
For the subroutines RESULT contains the result. IFLAG is used to select the following:
IFLAG=0, RESULT = X + S IFLAG=1, RESULT = X- S IFLAG=2, RESULT = -X + S IFLAG=3, RESULT = -X - S Precision is Inputs Result Internal MC032AS/SSPS Single Single Double MC032AD/DSPS Single Double Double MC032AP/DSPP Double Double Double MC032AQ/DSPD Double Double Quadruple
IBM 360 Assembler.
MC03AS, MC03AD, MC03AP, MC03AQ are separate subroutines. Each has eight arguments. The last two are Integer the remainder as described above. SSPS,DSPS,DSPP and DSPD are separate Functions with Type and arguments as given above. No subsidiary routine is required.
All these Subroutines and Functions are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
R Taylor
Although these routines can be used to compute elements in a matrix multiplication, the user is advised to use one of SMMS, DMMS, DMMD (AL/19,20,21) which do matrix multiplication using the same techniques as used here.
A suite of routines is available for computing matrix products i.e. C(I,J) = A(I,x) * B(x,J) summed over x for all I and J. These routines obtain greater accuracy through the extra precision of internal working, and extra speed through the ability of the 195 to perform two multiplications simultaneously. The various forms allow the user to specify Single or Double Precision for input arguments and output arguments.
SMMS is about three times faster than an equivalent routine written in Fortran, and about twice as fast as the routines in the SSPS family (AL/12, etc).
(i) REAL A(IDA,JDA), B(IDB,JDB)f, C(IDC,JDC)
CALL SMMS (A, IDA, B, IDB, C, IDC, K, L, M)
will multiply the K-by-L matrix A by the L-by-M matrix B to form the K-by-M matrix C. The numbers IDA, IDB and IDC are the first dimensions of the arrays A, B and C. Therefore it is necessary that 0 < K <= IDA, K <= IDC and 0 < L <= IDB.
(ii) DMMS is called in the same way as SMMS except that C must be declared as Double Precision.
(iii) DMMD is called in the same way as SMMS except that A, B and C must be declared as Double Precision.
In the following cases:
(i) K < 1 or M < 1;
(ii) L < 1;
(iii) K > IDA or K > IDC or L > IDB;
C(1,1) is set as an undefined variable (Hexadecimal 77777777) and the call is ignored.
IBM 360 Assembler.
SMMS, DMMS, DMMD are separate subroutines. Each Has nine arguments. Arguments 2, 4, 6 and the last three are Integer, the others are described above. No subsidiary routine is required.
SMMS and DMMS and DMMD are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
C Severn
(a) CALL SSORT (A, N, L)
N character strings each of L bytes in length, stored consecutively in the array beginning at the high order byte of A(1)
string 1 string 2 string 3 string 4 ... A(1)
will be sorted into ascending order according to the following rule.
Suppose there are two character strings A and B composed of bytes a1,a2,...,aL and b1,b2,...,bL respectively. Each byte has a value in the range (0,255). If a1 > b1 then A > B; If a1 = b1, but a2 > b2 then A > B and so on; only if ai = bi for i=1 to L does A = B.
A Shell Sort method is used. The strings will be sorted into ascending order provided that: (i) N > 1 ; and (ii) 0 < L < 257. If either condition is violated, no sort is attempted.
The full collation sequence is given in the manual Principles of Operation, GA22-7000, copies of which should be available at workstations. It is also on the Yellow Card System/370 Reference Summary. The basic sequence is: blank, special characters, lower case letters, upper case letters, digits.
(b) CALL SSORT (A, N ) is equivalent to
CALL SSORT (A, N, 4)
IBM 360 Assembler.
SSORT is a subroutine with three arguments, the second two must be Integer, though the third may be omitted. No subsidiary routine or work area is required.
SSORT is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
Modifications by P J Hemmings
CALL ASORT (ARRAY, N) N > 0
CALL DSORT (DARRAY, N)
CALL ISORT (IARRAY, N)
These are three subroutines for sorting Real, Double Precision, and Integer arrays into descending arithmetic order. A Shell Sort method is used.
If N < 1 no sort is attempted. The user should also ensure that N is not larger than the dimension of the array.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
These are three separate subroutines each with two arguments. The second argument must be Integer. The first argument is an array which must be Real, Double Precision, or Integer respectively. No subsidiary routine or work area is required.
ASORT, DSORT and ISORT are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
(a) CALL SLL (A, K, N ) N > 0 or CALL SRL (A, K, N ) and 0 < K < 33
A is an array of N 4-byte words of any Type. Each word in the array is processed in turn beginning with A(1). The binary pattern of each word is shifted K places. SLL shifts to the left, ie towards the high order position. SRL shifts to the right. Vacated positions are filled with zeros. Bits which spill are lost.
(b) CALL SLL (A, K, N, L ) N > 0, L = 2, 4, 8 or CALL SRL (A, K, N, L ) and 0 < K < KMAX + 1
A is an array of N words, whose length is given by L as one of the permitted values 2, 4 or 8. Shifting is performed as described above. KMAX is the length of the maximum shift and depends on L, taking the values 16, 32 and 64, when L = 2, 4 and 8 respectively.
The subroutine call is ignored when:
(a) N < 1;
(b) K < 1;
(c) L is not 2, 4 or 8 (Usage (b) only);
(d) K > 32 in Usage(a);
(e) K > KMAX in Usage (b).
The use of SLL with a shift count of K on Fortran Integers is equivalent to multiplication by 2**K for both positive and negative numbers provided the magnitude of the result is less than 2**31. The use of SRL with a shift count of K on Fortran Integers is equivalent to division by 2**K for positive numbers only.
IBM 360 Assembler.
SLL and SRL are entry points in a routine called SHIFT. Each has four arguments, though the fourth may be omitted. The first argument may be of any Type. The others must be Integer. No subsidiary routine or work area is required.
SLL and SRL are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
L T Jones and N Macleod
(a) CALL SLLS (A, B, K, N) N > 0 or CALL SRLS (A, B, K, N) and 0 < K < 33
A and B are arrays of N 4-byte words of any Type. Each word in the array A is processed in turn beginning with A(1). The binary pattern of each word is shifted K places. SLLS shifts to the left, ie towards the high order position. SRLS shifts to the right. Vacated positions are filled with zeros. Bits which spill are shifted into the corresponding wording in the array B and the remaining positions of the words in B are filled with zeros.
(b) CALL SLLS (A, B, K, N, L) N > 0, L = 2,4,8 or CALL SRLS (A, B, K, N, L) 0 < K < KMAX+1
A and B are arrays of N words, whose length is given by L as one of the permitted values 2, 4 or 8. Shifting is performed as described above. KMAX is the length of the maximum shift and depends on L, taking the values 16, 32 and 64, when L = 2, 4 and 8 respectively.
The subroutine call is ignored when:
(a) N < 1;
(b) K < 1;
(c) L is not 2, 4 or 8 (Usage (b) only);
(d) K > 32 in Usage(a);
(e) K > KMAX in Usage (b).
The user should ensure that A(N) and B(N) are valid locations.
IBM 360 Assembler.
SLLS and SRLS are entry points in a routine called XSHIFT. Each has five arguments, though the fifth may be omitted. The first two arguments may be of any Type. The others must be Integer. No subsidiary routine or work area is required.
SLLS and SRLS are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
L T Jones and N Macleod
Fortran Integer variables require 4 bytes for each word unless the INTEGER*2 declaration is used. When working with numbers with a small range of values, one can economise on the storage requirement by packing numbers into fields. The fields lie within a storage area which may consist of a single variable or of an array.
It is expedient to use this technique when performing unformatted binary input/output of such numbers.
Two groups of routines are included. The Single-Byte group is suitable for numbers in the range (0,255). The Half-Word group is suitable for numbers in the range (0,65535).
(a) Single-byte packing of one integer
CALL PACK8 (W, I, J) -1 < I < 256 , J > 0
stores the value of I in the J-th byte of W.
CALL UNPK8 (W, I, J) J > 0
stores the value of the J-th byte in I.
(b) Packing Four Integers into One Four Byte Word
CALL SHUT8 (W, K) -1 < K < 255 for I=1,4
stores the values of the Integers K(1), K(2), K(3) and K(4) in the first four bytes of W.
CALL OPEN8 (W, K)
stores byte 1 of W in K(1), byte 2 in K(2), byte 3 in K(3), and byte 4 in K(4).
(c) Half-Word Packing of One Integer
CALL PACK16(W, I, J) -1 < I < 65535 , J > 0
stores the value of I in the J-th half-word of W.
CALL UNPK16 (W, I, J) J > 0
stores the J-th half-word of W in I.
(d) Packing Two Integers into Adjacent Half-Word
CALL SHUT16 (W, K) -1 < K(I) < 65536 , I=1,2
stores the values of K(1) and K(2) in half-words 1 and 2 of W.
CALL OPEN16 (W, K)
stores the first half-word of W in K(1) and the second in K(2).
(a) I > 255 for PACK8
I > 65535 for PACK16
K(I) > 255 for SHUT8 where I=1, 2, 3 or 4
K(I) > 65535 for SHUT16 where I=1 or 2
only the low order part of the number is stored, i.e. CALL PACK8 (W,296,J) and CALL PACK8 (W,40,J) are equivalent.
(b) I < 0 for PACK8 or PACK16 K(I) < 0 for SHUT8 or SHUT16
Let I' = 2**32 + I , then I' will be stored subject to the provisions of error (a).
(c) J out of bounds (see below) has the following possibilities:
(i) Addressing Error (OC5)
(ii) Protection Error (OC4)
(iii) Overwriting one's program.
In the descriptions W is a storage area. It must be defined by the user so that it is large enough to accommodate the correct number of bytes. For example, suppose an area of 5 bytes is required, then any of the following would serve: REAL*8 W; INTEGER W(2); INTEGER*2 W(3); LOGICAL*1 W(5). If W is used merely for storing and retrieving numbers, its Type is not important.
IBM 360 Assembler.
PACKER is a subroutine with eight entry points. I, J, K must be Integer when used. See above for discussion on W. No subsidiary routine or work area is required.
PACKER is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
DOUBLE PRECISION X,Y
CALL CRACK (X,Y,K)
will return values of Y and K defined as follows.
When X ≠ 0 then X = Y * (2**K) where 0.5 <= DABS(Y) < 1.0
If X = 0 then Y = 0 and K = 0
N.B. The output is always to a Double Precision word for Y, but if the input X is in Single Precision one may proceed as in the following example.
REAL A(20)
DOUBLE PRECISION B(20)
CALL CRACK (DBLE(A(I)) , B(I) , K)
IBM 360 Assembler.
CRACK is a subroutine with three arguments. The first two are Double Precision and the third is Integer. No subsidiary routine is required.
CRACK is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
P J Hemmings
Subroutines UNBIT4 and REBIT4 allow bit strings to be unpacked into and repacked from an array of INTEGER*4 or LOGICAL*4 variables. UNBIT1 and REBIT1 are the LOGICAL*1 equivalents.
(a) CALL UNBIT4 (BITS, IFLAG, N) N > 0
will unpack a bit string of length N from the word or array BITS into the array IFLAG. The first element of IFLAG corresponds to the leftmost (most significant) bit of BITS. If IFLAG is an Integer array, each element is set to the value (0 or 1) of the corresponding bit. If it is a Logical array, the values 0 and 1 correspond to .FALSE, and .TRUE. respectively. There is no restriction on the alignment of the array BITS (it can be LOGICAL*1) and no upper limit exists for the value of N (apart from the dimension of the IFLAG array).
(b) CALL REBIT4 (BITS, IFLAG, N) N > 0
will repack a bit string of length N from the array IFLAG into the word or array BITS. Thus REBIT4 will repack a bit string unpacked by UNBIT4. A bit is set in BITS if and only if the corresponding element of IFLAG is positive. Again there is no restriction on BITS or limit on N. However, if N is not a multiple of 8, the last byte stored in the BITS array will be padded with binary zeros on the right. E.g. if N=11, the last 5 bits of the second byte of BITS will be set to zero. Any subsequent bytes will remain unchanged.
(c) CALL UNBIT1 (BITS, IFLAG, N) N > 0
acts as (a) except that here IFLAG is Logical*1.
(d) CALL REBIT1 (BITS, IFLAG, N) N > 0
acts as (b) where IFLAG is Logical*1. The bit is zero if and only if the byte is zero.
IBM 360 Assembler.
These are four separate subroutines each having three arguments. No subsidiary routines are required.
All four are are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
J C Hart
The routine TRCONV translates a buffer (array) of text in a particular character code into a different code in a different array. The arrays may be of any length, and may coincide, in which case the translated text replaces the original. The translation table is specified by name and is dynamically loaded. Translation tables may be explicitly loaded and deleted to optimize performance.
In the following examples, assume:
LOGICAL*1 IN(L),OUT(L),NAME(4)
INTEGER*4 L,IFLAG
TRCONV: CALL TRCONV (NAME, IN, OUT, L)
TRLOAD: CALL TRLOAD (NAME)
TRDELE: CALL TRDELE (NAME)
TR$SET: CALL TR$SET (IFLAG)
The arrays IN and OUT are the original and the translated text respectively. They may be any length, but neither smaller than L in the call to TRCONV. If IN and OUT are different, the text in IN is moved to OUT and translated. If they are the same location, the text in IN is translated in place. The translation table to be used by TRCONV is identified by a four byte name such as AOEO.
If TRCONV is called without any previous call to TRLOAD, the translation table required is loaded, used for the translation and deleted. To save this overhead, the user may call TRLOAD to preload translate tables. Subsequent calls to TRCONV will then find the preloaded table much faster than if a fresh load was needed. If a user knows he has finished with a table for the time being, he may delete by calling TRDELE.
Multiple calls to TRLOAD (without intervening calls to TRDELE) merely increment a local use count; TRDELE only deletes the module when the local use count is zero.
For details of TR$SET, see the section on 'Errors' below.
The translation tables currently available are:
AOEO standard RL ASCII to standard RL EBCDIC EOAO standard RL EBCDIC to standard RL ASCII
Note that in these tables, characters in EBCDIC with no equivalent in ASCII are converted to percent (%). The list of tables will be added to, and updates will be circulated.
Error handling is controlled by a switch which may be changed by calling TR$SET. It may have the following values:
0 do not produce messages or abend 1 produce messages but do not abend 2 abend but do not produce messages 3 produces messages and abend
Initially it is set to 3. There are three possible errors:
code number message 3781 TRT001S wrong number of parameters at call 3782 TRT002S translate table module not found 3783 TRT003S length specified -ve or > 16Mbytes
All routines may get error 1; TRCONV and TRLOAD may get error 2; only TRCONV may get error 3. TRDELE deleting a module that is not loaded is not regarded as an error. If the no abend option is used, the routines return a return code of 4 ( equivalent to RETURN 1) when an error is noted.
IBM 360 Assembler.
The package is written using R#PACK, which generates an interface module (TR#USER), a workspace module (TR#WORK) and a re-entrant, dynamically loaded code section (TR#RENT).
The user interface and associated workspace are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
C D Osland
Standard Character Codes for the RL Central Computer System (RL-76-121/C).
USWOP1 interchanges the contents of two arrays of length N bytes without the use of intermediate storage.
CALL USWOP1 (A, B, N) where N > 0
moves N bytes of array A into array B and vice versa. A and B may be arrays of any type; there is no conversion when they are of differing types. If the arrays A and B partially overlap, then results will be unpredictable; if A and B coincide, then the array is cleared to zero, though less efficiently than by means of CALL UFILL1(A,N,0).
If N < 1, then the call is ignored.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
USWOP1 is a subroutine having three arguments, the first two of which may be of any type; the third must be Integer*4. No subsidiary routines are required.
USWOP1 is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
C S Cooper
Integer function ICOMPR compares two arrays of N bytes using the ordering defined by IBM EBCDIC character code. The comparison is on a logical byte by byte basis: there is no type conversion.
IF (ICOMPR (A, E, N)) 1,2,3
will branch to statement 1, 2 or 3 when A < B, A = B or A > B, respectively. The values returned are -1, 0 and +1, respectively. If N < 1, then the result is 0.
IBM 360 Assembler.
ICOMPR is an Integer function subroutine having three arguments, the first two of which may be of any type; the third must be Integer*4. No subsidiary routines are required.
ICOMPR is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
C S Cooper
These routines may be used to manage bit tables, allowing individual bits to be set and tested. They can handle tables of arbitrary size, unlike the TBIT routines (DH/44-47) which are restricted to tables of up to 32 bits.
(a) DIMENSION TABLE(20)
CALL USETB (80, TABLE)
sets to 1 the 80th bit in the array TABLE. Note that the most significant bit in the table is defined as bit 1 and NOT bit 0.
(b) DIMENSION TABLE(20)
CALL UCLRB (80, TABLE)
sets to 0 the 80th bit in the array TABLE.
(c) DIMENSION TABLE(20)
CALL UFLIPB (20, TABLE)
logically complements the 80th bit in the array TABLE.
(d) DIMENSION TABLE(20) LOGICAL ITESTB
IF (ITESTB(80, TABLE)) GOTO 10
The logical function ITESTB returns the value .TRUE, if the specified bit is set to 1, otherwise it returns the value .FALSE..
IBM 360 Assembler.
USETB, UCLRB, UFLIPB and ITESTB are routines with two arguments, the first being a fullword integer and second being of any type. ITESTB returns a logical value.
The routines are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
J C Hart
Y = PB01AS (A, N, X) where N > -1
has the effect of computing
Y = A(1) + A(2)*X + ... + A(N+1)*(X**N)
but is much faster than Fortran. The coefficients of the polynomial are stored in the array A, whose Dimension must be at least N+1.
IBM 360 Assembler.
PB01AS is a Real function with three arguments, the first and third being Real and the second an Integer. No subsidiary routine is required.
PB01AS is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
R Taylor
(a) I = IRAND (M, 1) where 0 < M < 2**31
may be used to generate a sequence of positive integers which are distributed randomly in the range 0 to M-1. Such a sequence is reproducible between different runs.
(b) I = IRAND (0, 1)
may be used in place of (a) for M = 2**31. The whole range of Fortran Integers are possible.
(c) I - IRAND (M, IS) M > -1 , IS > 1
may be used to produce a reproducible sequence as for (a) or (b) but different sequences for each IS.
(d) I = IRAND (M, 0) M > -1
may be used to produce a sequence which will differ between runs. This is equivalent to (c) with IS computed from the time of day.
(e) I = IRAND (M) is equivalent to (d).
The second argument is only used during the first call of IRAND. If, however, IRAND is overlaid, the sequence will be reinitialised when IRAND is called after being reloaded. It is permitted to vary M between calls.
(i) If IS < 0 , IRAND is not defined.
(ii) If M < 0 , IRAND works as in (b) except that all numbers are multiples of 4.
The algorithm for generating IRAND is described in a Long Write-up.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
IRAND is an Integer Function with two Integer arguments. The second argument may be omitted. No subsidiary routine is required.
IRAND is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
L T Jones and N Macleod
The Bessel Functions Jo(x), Ji(x), Yo(x) and Yi(x), and the Modified Bessel Functions Io(x), Ii(x), Ko(x) and Ki(x), are available in both single and double precision arithmetic. Higher order Bessel Functions may be obtained from the recurrence relationships given in the Long Write-up.
Single Precision.
(a) Y = BJ0 (X) where 0 < X computes Jo(x) (b) Y = BJ1 (X) where 0 < X computes Ji(x) (c) Y = BY0 (X) where 0 < X computes Yo(x) (d) Y = BY1 (X) where 0 < X computes Yi(x) (e) Y = BI0 (X) where 0 < X < 174 computes Io(x) (f) Y = BI1 (X) where 0 < X < 174 computes Ii(x) (g) Y = BK0 (X) where 0 < X < 174 computes Ko(x) (h) Y = BK1 (X) where 0 < X < 174 computes Ki(x)
Double Precision.
The names of the Functions are prefixed by D as in the following examples:
(j) DOUBLE PRECISION X,Y,DBJ0
Y = DBJ0 (X)
(k) REAL*8 Y,DBK1
Y = DBK1 (1.3D0)
See the Long Write-up
(i) X < 0 , the function will be computed for the absolute value of X.
(ii) X = 0 (for BY0,,BY1,,BK0,,BK1 and DBY0,,DBY1,,DBK0, Fortran errors will occur due to attempts to divide by zero, calculate LOG(X) etc.
(iii) X > 174 (for BI0,BI1 and DBI0, DBI1) overflows occur attempting to calculate and use EXP(X).
(iv) X > 174 (for BKO, BK1 and DBK0, DBK1) underflows occur attempting to calculate and use EXP(-X)
ISO FORTRAN 77 compiled using IBM vs Fortran compiler.
0DBJ0 is a DOUBLE PRECISION FUNCTION which has one Double Precision argument. BJ0 which has one Single Precision argument is a secondary entry point of DBJ0. In each case the value of the function is returned as a Double Precision quantity. The calling routine must declare DBJ0 to be Double Precision otherwise it can only be used as Single Precision.
DBJ1(BJ1), DBY0(BY0), DBY1(BY1), DBI0(BI0), DBI1(BI1), DBK0(BK0), DBK1(BK1) all have a similar structure to DBJ0(BJ0). The only subsidiary routines required are the Fortran functions LOG, EXP, etc.
The Bessel Function routines are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
M M Curtis, with modifications by P J Hemmings.
REAL*8 BINOM,C
C = BINOM (N, I) where -1 < I < N+1.
will compute the binomial coefficient N!/((N-I): * I!)
If I < 0 , or if I > N , the coefficient is returned as zero.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
BINOM is a Double Precision Function with two Integer arguments. No subsidiary routine is required.
BINOM is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
P J Hemmings.
A binomial coefficient is always integral valued. BINOM returns a Double Precision result because the coefficient can be very large. C could be declared as Integer in the above example if it were known that the coefficient were less than 2*10**9. BINOM seeks to obtain maximum cancelling to avoid introducing too large numbers into the computation. If the value of the coefficient is greater than about 10**75 then overflow occurs.
The rotation matrix associated with spin j consists of terms djmn(theta) where j is normally written as a superscript and m and n are subscripts. Theta is the angle of rotation. Both m and n take one of the (2j+1) values between -j and +j. DJMN computes one term of this matrix, j must take half-integral values. (j-m) and (j+m) must both be integral valued.
DOUBLE PRECISION DJMN,THETA,EL
EL = DJMN (J2, M2, N2, THETA)
where J2 contains 2j, M2 contains 2m, N2 contains 2n, and THETA is the angle in radians. The following conditions must be satisfied:
(i) J2 > 0
(ii) -J2 < M2 < J2
(iii) -J2 < N2 < J2
(iv) (J2-M2) must be even.
(v) (J2-N2) must be even.
A computational limitation also exists in that overflows can occur with large values of J2 and one of M2 or N2. If M2 (or N2) is almost equal to J2, the limitation is seen at about J2=35. As M2 (or N2) decreases, the limitation occurs with larger values of J2. In practice few users will be affected by this.
If any of the conditions (i) to (v) are violated the result is given as zero.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
DJMN is a Double Precision Function which has four arguments. The first three must be Integer, the fourth Double Precision. DJMN requires the subsidiary routine BINOM (FN/19) and the Fortran mathematical routines DSQRT, DCOS, DSIN, DTAN.
DJMN is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
P J Hemmings
"Elementary Particles" by W R Frazer (Prentice-Hall 1966).
(a) DOUBLE PRECISION X,Y,PNM
Y = PNM (N, 0, X, IER)
where -1 < X < 1 and N > 0 , will compute the zero order Legendre Polynomial of order N.
(b) DOUBLE PRECISION X,Y,PNM
Y = PNM (N, M, X, IER)
where -1 < X < 1 and N > 0 , will compute the Associated Legendre Polynomial of order N and degree M.
IER is an error code which is returned as zero except when the absolute value of X exceeds 1. In that case IER is returned as 1.
The following relationships and definitions are used.
PNM (N, -M, X, IER) = PNM (N,M,X,IER) PNM (N, M, X, IER) = 0 when M > N. PNM (M, M,X, IER) can be computed from a recurrence relationship. PNM (N, M, X, IER) is computed from a further recurrence relationship,
(i) If N < 0 , PNM is returned as zero.
(ii) If ABS(X) > 1 , IER is set to 1, PNM to zero, and the following message is printed:
COS(THETA) FOR LEGENDRE POLYNOMIAL EXCEEDS UNITY AND THEREFORE IER SET TO ONE & PNM TO ZERO
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
PNM is a Double Precision Function which has four arguments. The third argument is Double Precision, the others all Integer. The only subsidiary routine required is that for Fortran output.
PNM is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
S M Deen with minor modifications by P J Hemmings.
"Special Functions" W W Bell (Van Nostrand,1968).
DOUBLE PRECISION Y, CGCOEF
Y = CGCOEF (J1, M1, J2, M2, J, M)
will compute the Clebsch-Gordan (Vector-Coupling) coefficient <j1,m1,j2,m2|j,m> where the spins j1 and j2 couple to form j, and the z-components are related as m=m1+m2. All the j's and m's take half-integral values, and to overcome this the arguments of the Function are:
J1 = 2j1 , M1 = 2m1 , J2 = 2j2 , M2 = 2m2 , J = 2j , and M = 2m .
The following conditions must apply:
(i) j-m , j1-m1 , j2-m2 must all be integral;
(ii) j + j1 + j2 must be integral;
(iii) |j1-j2| <= j <= j1+j2;
(iv) j.j >= m.m , j1.j1 >= m1.m1 , j2.j2 >= m2.m2;
(v) m = m1 + m2.
A computational limitation also exists in that overflows could occur when j+j1+j2 > 20 , but it also depends on the values of the m's.
If m=m1=m2=0 then use ABC (FN/23) which is faster.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
CGCOEF is a Double Precision Function with six Integer arguments. CGCOEF requires the subsidiary function FACT (FN/25) with its Common Block FACT$$, together with the Fortran DSQRT routine.
CGCOEF and FACT are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
G G Donaldson
"Angular Momentum in Quantum Mechanics" by A R Edmonds (Princetown University Press, 1957).
DOUBLE PRECISION Y,ABC
Y = ABC (IA, IB, IC)
where IA+IB+IC < 111, will compute the Clebsch-Gordan (Vector-Coupling) coefficient <j1,0,j2,0|j,0> where the spins j1 and j2 couple to form j, and the z-components are all zero. The j's may take half-integral values only. However, the coefficient takes nonzero values only when all the j's are positive integers, their sum is even, and the j's satisfy the three triangle inequalities:
j1+j2 <= j, j2+j <= j1, and j+j1 <= j2.
The arguments of the Function ABC are: IA=2j1 IB=2j2 and IC=2j. The quantities j1, j2 and j are sometimes referred to as a, b and c. Hence the name of the Function.
A computational limitation exists such that if j+j1+j2 > 55 overflows occur and the value of the function is not valid.
(i) If IA+IB+IC > 110, overflows occur. The result will not be valid.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
ABC is a Double Precision Function with three Integer arguments. ABC requires the subsidiary functions DELTA (FN/24) and FACT (FN/25) with the associated Common Block /FACT$$/.
ABC and the routines it needs are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
S M Deen modified by P J Hemmings.
"Kinematics of Nuclear Reactions" A Baldin et al. (Pergamon Press,1961).
The Triangular Function DELTA(a,b,c) is defined as follows: when a, b and c are multiples of 1/2, a+b+c is integral, 0<=a<=b+c, 0<=b<=c+a, 0<=c<=a+b and a+b+c+l>=0, DELTA(a,b,c) is the square root of
(b+c-a)! (c+a-b)! (a+b-c)! / (a+b+c+1)!
Otherwise DELTA(a,b,c) = 0.
DOUBLE PRECISION F,DELTA
F = DELTA (IA, IB, IC)
where IA, IB and IC contain 2a, 2b and 2c respectively. There is a computational limitation in that if a+b+c>55 then overflows occur and the result is not valid.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
DELTA is a Double Precision Function with three Integer arguments. DELTA invokes the Function FACT (FN/25) and its Common Block /FACT&&/. Space is also required for FACT and FACT&&.
DELTA and FACT are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
S M Deen modified by P J Hemmings.
"Kinematics of Nuclear Reactions" by A Baldin et al. (Pergamon Press,1961).
DOUBLE PRECISION F,FACT
F = FACT (N) where 0 < N < 56
will compute N! as a Double Precision number.
When N < 22, N! is returned precisely, but when N > 21, N! needs more than 16 significant figures and FACT returns a rounded number.
(i) N < 0, FACT is returned as zero.
(ii) N > 56, N! exceeds the largest number permitted in IBM 360 or 370 arithmetic, and overflow occurs,
(iii) Failure to declare FACT as Double Precision causes the result to be truncated to six significant figures, precise only when N < 11.
FACT merely obtains N! from a table in the Common Block /FACT&&/. A program may access this table directly and avoid the overhead of subroutine calling. This is done as follows:
DOUBLE PRECISION F,FACT,FACTO
COMMON /FACT&&/ FACTO,FACT(56)
F = FACT (N)
and the Link-Edit control statement is needed
INCLUDE SYSLIB(FACT$$)
It is up to the user to ensure N is valid. N.B. If the user program makes use of any of the Functions which use FACT, e.g. DELTA (FN/24), the INCLUDE card is not necessary.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
FACT is a Double Precision Function with a single Integer argument and it refers to the Common Block labelled FACT&&. No subsidiary routines are required.
FACT is in the Automatic Call Library. It is available in CMS. FACT$$ requires a specific INCLUDE statement unless invoked by another routine.
P J Hemmings
Warning; Avoid expressions which risk overflow such as
Y = (FACT(I)*FACT(J)*FACT(K))/(FACT(L)*FACT(K)*FACT(N))
Where possible alternate multiplication and divisions.
The Racah coefficient W(a,b,c,d,e,f) for the recoupling of 3 angular momenta is described in the reference. The arguments are multiples of 1/2, and in order to obtain a non-zero coefficient each of the triplets (abe) (cde) (bdf) (afc) should sum to whole numbers and satisfy the triangle inequalities e.g. 0<=a<=b+c, 0<=b<=c+a and 0<=c<=a+b.
"Kinematics of Nuclear Reactions" A Baldin et al. (Pergamon Press,1961).
DOUBLE PRECISION Y,RACAHW
Y = RACAHW (IA, IB, IC, ID, IE, IF)
where IA=2a, IB=2b, IC=2c, ID=2d, IE=2e, and IF=2f. Each argument must be positive or zero. If the perimeter of any of the above "triangles" exceeds 50, then the evaluation of RACAHW risks overflows.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
RACAHW is a Double Precision Function with six Integer arguments. RACAHW requires the subsidiary routines DELTA (FN/24) and FACT (FN/25).
RACAHW, DELTA and FACT are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
S M Deen modified by P J Hemmings.
The Racah coefficient W(a,b,c,d,e,f,g,h,i) for the recoupling of 4 angular momenta is described in the reference. The arguments of X must all be multiples of 1/2 to obtain a non-zero coefficient.
"Kinematics of Nuclear Reactions" A Baldin et al. (Pergamon Press,1961).
DOUBLE PRECISION Y,RACAHX
Y = RACAHX (IA, IB, IC, ID, IE, IF, IG, IH, II)
where IA=2a, IB=2b, .. II=2i. Each argument must be positive or zero otherwise RACAHX will be returned as zero.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
RACAHX is a Double Precision Function with nine Integer arguments. RACAHW requires the subsidiary routines DELTA (FN/24) and FACT (FN/25).
RACAHX is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
S M Deen
The Racah coefficient Z(a,b,c,d,e,f) for the recoupling of 3 angular momenta is related to the Racah W coefficient. It is defined by the formula:
Z(a,b,c,d,e,f) = (-l)**s . SQRT ( (2a+l)(2b+l)(2c+l)(2d+l) ) . W(a,b,c,d,e,f) . <a,0,c,0|f,0>
where s=a+b+c+d+e+f and <a,0,c,o|f,0> is the Clebsch-Gordan coefficient with zero z-components. The parameters a,b,c,d,e,f must be multiples of 1/2 for a non-zero coefficient. Further, since <a,0,c,0|f,O> is zero when a+c+f is odd, Z=0 when a+c+f is an odd integer.
DOUBLE PRECISION Y,RACAHZ
Y = RACAHZ ( IA, IB, IC, ID, IE, IF)
where IA=2a, IB=2b, IC=2c, ID=2d, IE=2e and IF=2f. Each argument must be positive or zero (see write-up of RACAHW FN/26).
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
RACAHZ is a Double Precision Function with six Integer arguments. The following subsidiary routines are required: ABC (FN/23), DELTA (FN/24)r FACT (FN/25), and RACAHW (FN/26) plus the Fortran square root function.
RACAHZ is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
S M Deen
"Kinematics of Nuclear Reactions" A Baldin et al. (Pergamon Press,1961).
The present version of ENPLOT (GR/2) supercedes the earliest versions. The major interfaces with the user's program are identical with the exception that CALL CONTRO (999) to output plots was replaced by CALL ENPLOT.
A minor interface CALL ENPLOT (-1) in all counts to zero. In the later versions CALL EN$ZER is required for this.
A subroutine CONTRO has been placed in the Automatic Call Library for compatibility with programs developed with the old ENPLOT versions. A full discussion of former versions is given in Appendix IV of the ENPLOT Long Write-up (RHEL/M/C50).
(a) CALL CONTRO (999) or CALL CONTRO (K) where K is not -1 acts as CALL ENPLOT (b) CALL CONTRO (-1) or CALL CONTRO (K) when K = -1 acts as CALL EN$ZER
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
CONTRO is a subroutine with one Integer argument. CONTRO requires the subroutines of the ENPLOT package.
CONTRO and ENPLOT are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
P J Hemmings
See "ENPLOT - A Program Package for the production of Histograms and Scatter Plots", P J Hemmings (RHEL/M/C50)
ENPLOT is a set of routines for producing line printer histograms and scatter plots with minimal interaction with a user program.
(a) CALL PILOT (M, N)
initialises the plotting package, reads the input for the package from stream M, and defines the output stream N. For card reader input and line printer output CALL PILOT (5,6).
(b) CALL PLOT ( X, N )
scores the quantity X in the histogram labelled N.
(c) CALL DPLOT ( Y, X, N)
scores the point (X,Y) in the scatter plot N.
(d) CALL ENPLOT
prints the histograms and scatter plots defined by the Call of Pilot, (e) Other facilities are available which are described in the Long Write-up.
Control cards as described in the Long Write-up.
ISO FORTRAN 77 compiled using IBM VS Fortran compiler.
ENPLOT is a collection of nine subroutines (PILOT, EN$AS, EN$ZER which has a secondary Entry EN$CH, PLOT, DPLOT, ENPLOT, EN$AX, EN$OP and EN$ODP) and two labelled Common Blocks (EN$1 and EN$2).
ENPLOT is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. However, it will only be found there as long as the user program has a CALL PILOT without which the other Calls are meaningless. It is not available in CMS.
RHEL/M/C50 "ENPLOT - A Program Package for the Production of Histograms and Scatter Plots", P J Hemmings.
Page 8 last line should have 1.0,2.0,3.0,4.0,5.0,6.0
Page 9 lines 2 to 5, interchange X and Y.
Page 11 interchange IA and JA in the table.
It is sometimes necessary to read magnetic tapes (particularly 7-track tapes) which have been written on other computers and are not written in a form which is acceptable to the IBM/360 Operating System. When a short record is found for example, OS checks the record 100 times before rejecting it. Consequently potentially useful information is lost and time is wasted. The purpose of EXCPIN is to retrieve as much information as possible from defective records.
The routine EXCPIN has been amended from an earlier version so that tapes with many physical files may be read a single file. It is thus permitted to continue reading beyond Tape Marks. Complete blocks are read with no attempt being made to separate data from control words or to define the start and end of Fortran Logical Records.
(a) CALL EXCPIN (ARRAY, NBYTE, NWL) NWL > 0
ARRAY is a storage area for words of length NWL bytes. Each call attempts to read a physical record of data. Each stripe is copied into the least significant byte of successive elements of ARRAY. The other bytes are set zero.
The maximum number of stripes that can be copied is determined by the BLKSIZE parameter given on the DD card for the tape. The length of the record is indicated by NBYTE as follows:
(i) NBYTE > 0 No input/output error occurred. The number of stripes copied is NBYTE.
(ii) NBYTE < 0 An input/output error occurred. The number of stripes is given by -NBYTE.
(iii) NBYTE = 0 An end-file mark was encountered.
Any subsequent call of EXCPIN will be from the next sequential data set (EXCPF002 etc. up to EXCPF999) for which DD cards will be required.
(b) CALL EXCPIN (ARRAY, NBYTE, NWL, 0) NWL > 0
is exactly equivalent to (a).
(c) CALL EXCPIN (ARRAY, KBYTE, NWL, N) NWL > 0
and N > 0 is as described in (a), except that one may continue past end-file marks without requiring extra JCL. It is therefore suitable for reading a multifile tape.
(d) CALL EXCPIN ( ARRAY, NBYTE, NWL, N ) NWL > 0
and N < 0 , will 'Close' the data set. That is, force an End of Data Set situation and put NBYTE=0 , so that any subsequent call of EXCPIN will be from EXCPF002 as in (a).
Note: NWL may be any positive integer. It is not restricted to 1, 2, 4, 8, 16 or 32.
A DD card with the name EXCPF001 for the first file
//EXCPF001 DD UNIT=unit,VOL=SER=volume,DISP=OLD, // LABEL=(file,BLP), // DCB=(DEN=den,RECFM=U,BLKSIZE=blksize)
blksize should be the largest number of words that ARRAY can accommodate. Records longer than this will be truncated.
Following an end-file after usage (a), (b) or (d), further reading requires another JCL card with ddname EXCPF002 and so on up to EXCPF999.
(i) Failure to provide a DD card causes the Fortran error condition IHC219I. An end-file condition is simulated.
(ii) NWL < 1 will be processed as if NWL=1.
IBM 360 Assembler.
EXCPIN is a subroutine with four arguments, the last of which is optional. Arguments two, three and for are Integer. The first argument is a storage area which will normally be an Integer array. EXCPIN requires the Fortran Error Monitor ERRMON.
EXCPIN is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
M J Mitchell (modifications by P J Hemmings).
The functions LCS and KCS with their associated Entry Points FRELCS and FREKCS are now identical to MAINCS and its associate FRMAIN which is described below. LCS and KCS are for compatibility with programs written for the IBM360 model 75 which used the Large Core Store feature.
Suppose a program has a single dimensioned array A. This can be extended dynamically into the area of Main Core allocated to your job-step by executing the following statement:
N = MAINCS (A, L, I)
where I is the number of bytes in an element of A (e.g. 4 for a Real Variable), L is the number of words or elements needed. N will be set to an integer which signals the success or failure to obtain the core requested.
When the request is successful, N is positive and the program may refer to the extra core as locations
A(N+K) for K=1,L
When the request is unsuccessful, the reason is indicated by the value of N as follows:
(i) N = 0 , requested is not available.
(ii) N = -1 ,I is not consistent with Type of A.
(iii) N = -2 , L < 1
(iv) N = -3 , I is not one of 1,2,4,8,16 or 32.
(v) N = -4 , see below
Storage is released by CALL FRMAIN which releases the last block obtained using MAINCS. If more than six uses are made of the MAINCS function without an intervening CALL FRMAIN then an error value of N = -4 will be returned.
Two dimensional arrays could be handled by use of EQUIVALENCE statements, but it is recommended that linear arrays be used with computed subscripts.
Users are reminded that the Fortran REWIND statement releases the buffer space used by a data set, which could then be used again by calling MAINCS.
The REGION parameter on the EXEC card should request sufficient space for the program, its buffers and for the core to be obtained by MAINCS.
IBM 360 Assembler.
MAINCS is an Integer Function with three arguments, the last two of which are Integer. FRMAIN is a secondary Entry Point of MAINCS. No subsidiary routines are required.
MAINCS. etc. are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are not available in CMS.
G K Caulton
(a) X = CLOCK (TIME, DATE)
will calculate the time of day (in seconds) as the value of the Function. Two character strings eight bytes in length are formed and stored in the arguments TIME and DATE.
The arguments TIME and DATE are created in a form suitable for printing using the A8 Format. Thus:
TIME = 'HH MM SS1 e.g. 23 59 59 DATE = ' DDMMMYY' 06JUL86
The arguments TIME and DATE should either be REAL*8 variables or arrays with Dimension large enough to accommodate a string of 8 bytes.
(b) X = CLOCK (TIME)
is as above but the string for the date is not required.
(c) CALL CLOCK (TIME, DATE)
is as (a) with only the character strings required.
(d) CALL CLOCK (TIME)
when TIME only is required.
IBM 360 Assembler.
CLOCK is a Real Function with two arguments which may be of any Type. The second argument may be omitted. CLOCK may also be called as a subroutine. No subsidiary routines are required.
CLOCK is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
L T Jones and N Macleod. CMS version by C P Wood.
K = KLOCK (ITIME)
K is set to the time of day measured in hundredths of seconds since midnight, i.e. an integer in the range 0 to 8640000.
Further, the Integer array ITIME is set as follows:
ITIME(1) = hour of the day (0 to 23) ITIME(2) = minute of the hour (0 to 59) ITIME(3) = second of the minute (0 to 59)
IBM 360 Assembler.
KLOCK is an Integer Function with one argument which is an Integer array whose Dimension is at least three. No subsidiary routines are required.
KLOCK is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
T Noland. CMS version by C P Wood.
(a) CALL DATE (IDAY, MONTH, IYEAR, LDAY)
the first three arguments will be set as integers to the day of the month, the month of the year, and the year of the century respectively, e.g. 25, 12 and 75. LDAY is set as a four byte character string to three characters identifying the day of the week plus a blank eg 'THU '.
(b) CALL DATE ( IDAY, MONTH, IYEAR )
is as (a) but no character string is produced for the day of the week.
IBM 360 Assembler.
DATE is a subroutine with four arguments, the last of which is optional. The first three arguments must be Integer, the fourth when given may be of any Type. No subsidiary routines are required.
DATE is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
T Noland. CMS version by C P Wood.
Associated with each program there are four bits in the Program Status Word called the Program Mask. These bits enable (when 1) or disable (when 0) program interruptions due to: fixed-point overflow; decimal overflow; floating-point exponent underflow; and significance exceptions. The meaning of these interruptions, and how the arithmetic process completes, is described in the Principles of Operation Manual.
The Fortran default setting for these bits is 0010 i.e. only exponent underflow interruptions are enabled. It is possible to change the setting of the mask using SPM and to examine the setting using GPM.
The divide and exponent-overflow exceptions cannot be disabled in this way. The VS Fortran Library contains a routine XUFLOW to enable/disable floating point exponent underflow interrupts. If only this facility is needed then XUFLOW is simpler to use.
(a) CALL SPM (IFIXOV, IDECOV, IEXUND, ISIG) eg CALL SPM (1,0,1,1)
when an argument is zero, the corresponding mask bit is set zero, otherwise the bit is set to one.
(b) CALL GPM (IFIXOV, IDECOV, IEXUND, ISIG)
the arguments are set equal to the corresponding mask bit. N.B. The arguments of GPM must all be variable, never constants as in the second example of SPM.
IBM 360 Assembler.
SPM and GPM are separate subroutines, each of which has four Integer arguments. No subsidiary routines are required.
SPM and GPM are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
R Taylor
REAL*8 LABEL, TLABEL
LABEL = TLABEL (N)
will obtain the serial number of the tape or disk associated with Fortran Stream N. The field is right adjusted i.e. two blanks precede the six character VOLUME name. Suppose your JCL contains:
//G.FT09F001 DD UNIT=TAPE9,DISP=OLD,DSN=XYZ, // VOL=SER=987654
then LABEL = TLABEL(9) will set the REAL*8 variable LABEL to the character string ' 987654' which may be printed using A8 Format.
(i) No stream N, TLABEL returns 0.0D0
(ii) N < 0 , the negative sign is ignored.
(iii) N > 99 , then N modulo 100 is used.
(iv) The JCL does not specify a tape or disk. One of the following strings is returned: 'DUMMY ', 'SYSOUT=A', 'SYSOUT=B', '* ' or 'INTERNAL'.
(v) Multiple streams N e.g. FT09F001, FT09F002, etc. TLABEL returns the volume name for the first data set defined in the JCL. For multiple streams one should therefore use TFILAB (SY/28).
IBM 360 Assembler.
TLABEL is a REAL*8 Function which has one Integer argument. No subsidiary routines are required.
TLABEL is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
Revision by P J Hemmings.
TFILAB (SY/28) performs a similar function to TLABEL.
The Fortran DEFINE FILE statement may only be used with constants for the number of records, for the maximum size of record, and for the stream number. Consequently statements such as
DEFINE FILE N (NREC, LENGTH, U, IVAR)
would be regarded as syntax errors. The subroutine DEFINU allows one to overcome this.
CALL DEFINU (N, NRECf LENGTH, IVAR)
would have the effect desired above. N is the Fortran stream number. NREC is the maximum record number. LENGTH is the record size measured in four-byte words. IVAR is the associated variable. This facility is only available for unformatted records.
IBM 360 Assembler.
DEFINU is a subroutine with four Integer arguments. The Fortran I/O routines are required.
DEFINU is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
M J Mitchell
CPULFT returns the CPU time used by or left to a job. CPULFT is available in MVS and CMS but when used online in CMS it requires initialisation by a call to CPUSET (see below).
(a) REAL*8 A, CPULFT
A = CPULFT (0)
will set A equal to the amount of CPU time (measured in minutes) remaining before the job reaches the TIME EXCEEDED condition.
(b) REAL*8 A, CPULFT
A = CPULFT (1)
will set A to the total amount of CPU time (measured in minutes used so far by this job on this step and any previous steps.
CPUSET is an entry point to CPULFT available only in CMS. When used online in CMS, CPULFT must be initialised by a call to CPUSET. Further calls to CPUSET are ignored. All calls to CPUSET are ignored in CMS batch.
(c) REAL*8 A, TIME, CPULFT
DATA TIME /0.1D0/, IFLAG /0/
CALL CPUSET (TIME,IFLAG) A = CPULFT (0)
will create an imaginary time limit of 6 seconds relative to the current CPU time when CPUSET is called. If IFLAG is set to zero, then calls to CPULFT after the time limit has expired will simply return negative values. If IFLAG is set to one, then a 322 ABEND will be forced if CPULFT is called after the time limit has expired. IFLAG is an optional argument and has a default value of one.
CPULFT measures the CPU time accounted to your job. In CMS this is the total CPU time (TTIME). This consists of the time taken to execute your code plus certain system overheads. These are very variable, even at different times during the execution of the program.
It is considered that CPULFT will give reproducible results only when measuring intervals of 0.01 seconds or greater. Measured intervals will be multiples of 104 microseconds in MVS and multiples of 1 microsecond in CMS.
On the MVS system, CPU times are scaled so that they are approximately independent of the machine the job is running on. This is not true in CMS, where CPU times are dependent on the native machine. This means that a program on the 3081 will return different times depending on whether it is running in MVS or CMS.
IBM 360 Assembler.
In MVS CPULFT is a REAL*8 function with one argument. In CMS CPULFT has an additional entry point with one or two arguments. No subsidiary routines are required.
CPULFT is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
Modifications by M M Curtis. CMS version by C P Wood.
(a) CALL LINK ('PROG1 ')
locates the program, load module named PROG1 in STEPLIB, JOBLIE or LINKLIB, loads the program into core and begins to execute it. Note the blanks which pad the module name out to 8 characters. If any of the conditions are found which prevent the module loading or executing then an Abend will occur, (eg 606 - insufficient core, 706 - module not executable, 806 - module not found, 813 - data set not found on the disk). Note that your Region size must be large enough to accommodate both the called and the calling program.
When the called program finishes, i.e reaches a STOP statement or a RETURN in its MAIN program, or a Fortran termination due to excessive errors, control is returned to the calling program and the core required by the called program is freed.
If the called program Abends, then the calling program is unable to continue. Note that when both are Fortran programs there will be two PITFAL traces in the HASP log.
(b) CALL LINK ('PROG2 ' ,9,'123456789')
locates, loads and executes the program PROG2 as described above but also provides it with the information PARM='123456789'. The second argument in this case (and (c)) is the length of the character string supplied as the third argument. Padding blanks are not necessary in this character string.
(c) REAL*8 NAME/'PROG3'/
CALL LINK (NAME,3,'RUN',NCODE)
will locate, load and execute the program PROG3 and supply the information PARM='RUN'. PROG3 issues a return code which will be stored in NCODE. Note that the Fortran statement STOP n sets the return code to n.
It is not permitted for the second argument to be zero. If there is no PARM information to be passed then use form (d).
(d) CALL LINK ('PROG4 ', NCODE)
locates, loads and executes the module PROG4 and stores the return code in NCODE.
IBM 360 Assembler.
LINK is a subroutine with up to four arguments. The first argument is compulsory and must be a string of eight characters.
When there are more than two arguments, the second argument must be Integer and the third argument must be a character string whose length is given by the second argument. When the fourth argument is present it must be an Integer variable. When there are two arguments only, the second must be an Integer variable. No subsidiary routines are required.
LINK is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
T Noland
EXTERNAL TIMEUP
COMMON /T/ ITEST
ITEST = 0
CALL SETIME ( 5,TIMEUP )
CALL NEXT
IF ( ITEST.EQ.O ) GO TO 1
CALL FINISH
STOP
END
SUBROUTINE TIMEUP
COMMON /T/ ITEST
ITEST = 1
STOP (or RETURN)
END
In this example, a cpu time interval of 5 seconds is initiated and the routine TIMEUP is entered as soon as the interval completes. Thus the subroutine NEXT would be called repeatedly until the 5 seconds cpu time had been used. When the code for the subroutine TIMEUP has been executed, processing resumes at the point where the timing interruption occurred (presumably somewhere in NEXT). STOP does not (in the subroutine TIMEUP) therefore have its normal meaning in this context.
(b) EXTERNAL TIMEUP
CALL SETIME (INTVAL, TIMEUP, A, B,...,N)
this form may be used if the subroutine to be entered requires arguments i.e. SUBROUTINE TIMEUP (A,B,...,N). INTVAL is the number of seconds cpu time.
When TIMEUP is entered, each argument will have the value at the time of the interruption unless it is an expression. If it is an expression the value when SETIME was called will be used.
(c) CALL SETIME (0)
will cancel the request for the timed interval, Any Call of SETIME with only one argument will do this.
The subroutine TIMEUP can be more elaborate than the example given here. There is for example no restriction on performing input or output. Care must be taken not to enter subroutines that the main processing might be using. In particular SETIME may not be called. As noted above, execution cannot be terminated in TIMEUP but the example illustrates a technique for bringing a calculation to a close.
The user should also beware of optimising compilers such as the H-compiler or the H-extended compiler. If the statement CALL NEXT were to be replaced by code with no subroutine of function calls, the example given in (a) would not work, because the compiler would remember the value of ITEST set outside the loop. It needs the subroutine call to indicate the possibility of a variable in Common being changed.
IBM 360 Assembler.
SETIME is a subroutine with a variable number of arguments but not less than one. When there is only one argument its Type and value are irrelevant. When there is more than one argument, the first argument must be Integer, and the second argument must be the name of an Externally defined routine. Any further arguments must be as required by the subroutine to be entered at the expiry of the cpu time interval. SETIME does not require any other subroutine, except that named as the second argument.
SETIME is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
T Noland
The text string specified as the PARM parameter on a JCL EXEC statement or as argument to the CMS Start command may be copied into an array in the user's region by subroutine PARMST. The routine is called with 1, 2 or 3 parameters. In all the following examples, the assumed declarations are:
INTEGER*4 LENGTH,LENGH2
LOGICAL*! STRING(LENGTH)
(a) CALL PARMST(STRING)
or CALL PARMST(STRING,LENGTH)
The 'PARM' string from the JCL is copied into array 'STRING'. 'LENGTH' (if specified) is an input parameter giving the length of 'STRING'; if not given, 100 is assumed. If the JCL string is too short for 'STRING', it is padded with trailing blanks; if too long it is truncated on the right.
(b) CALL PARMST(STRING,LENGTH,LENGH2)
Exactly as for the examples above, except that 'LENGH2' will be set to the number of characters copied into 'STRING', after truncation but before padding, if either occurred.
IBM 360 Assembler.
None - this may be called from anywhere in a Fortran program, and may be called any number of times. It may be overlaid.
PARMST is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
C D Osland
This routine is smaller, faster and more flexible than routine PARM, and should be used instead of it. Note however that the order of the parameters is different, and the default length of 'STRING' is assumed to be 100 - the maximum allowed by JCL.
Six forms of use are shown. (a) is a special case of (b), and (c) is a special case of (d). (e) corresponds to the usage for a previous version of this routine and is a special case of (f). The subroutine returns a 44-byte character string which is either the fully qualified data set name (padded where necessary with trailing blanks), or the character string ' NO DD CARD FOR DDNAME dddddddd' which can be distinguished from a data set name because it begins with four blank characters.
(a) DIMENSION DSN(ll)
CALL DSNAME(3,DSN)
will return the name of the data set currently associated with stream 3.
(b) DIMENSION DSN(ll)
CALL DSNAME ( N, DSN) 0 < N < 51
will return the name of the data set currently associated with stream N, i.e. FTnnFxxx where nn is the two digit representation of N and xxx is the Fortran file number which is 001 initially and is incremented at each end of data set condition.
(c) DIMENSION DSN(11)
CALL DSNAME (12034, DSN)
will return the data set name associated with FT12F034.
(d) DIMENSION DSN(11)
CALL DSNAME (N,DSN) 999 < N < 51000
Let N = 1000*nn + fff, then DSNAME will return the data set name
(e) DIMENSION DSN(11)
CALL DSNAME ('FT01F001' ,DSN)
will return the data set name associated with FT01F001.
(f) DIMENSION DSN(11),DDNAME(2)
CALL DSNAME (DDNAME ,DSN)
where DDNAME is an 8-byte ddname, or a shorter ddname delimited by at least one blank, e.g. 'LIBI '. The routine will return the corresponding data set name.
(i) -16777216 < N < 1, NO DDCARD message given.
(ii) 50 < N < 1000, NO DDCARD message given.
(iii) N < 50000, NO DDCARD message given.
(iv) N < -16777215, the subroutine will treat N and the word following N as though it defined an area to be used as in usage (f). Thus up to 8 bytes would be used as a DDNAME almost certainly resulting in the NO DDCARD message.
(v) DSNAME defines an area of less than 44 bytes. The subroutine always returns 44 bytes, so overwriting will occur.
IBM 360 Assembler.
DSNAME is a subroutine with two arguments. The first argument may be either (a) an Integer, or (b) an area containing a character string of eight non-blank bytes, or (c) an area containing a character string of less than eight bytes but including at least one blank. The second argument is a storage area of 44 bytes. It may be defined in various ways e.g. INTEGER DSN(11), INTEGER*2 DSN(22), or LOGICAL*! DSN(44) are equally acceptable. DSNAME calls the subroutine GETDD (SY/21) and accesses the control block D$ETUP (SY/22).
DSNAME is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
T Noland with modifications by P J Hemmings.
(a) CALL GETDD (N,DDNAME)
where N is in the the range 1 to 99 will return an eight byte character string in DDNAME which is the ddname to be used for the next Fortran Read or Write using stream N. The file number is incremented after an ENDFILE statement or after taking the END= condition when reading. It is reset after a REWIND statement. However BACKSPACE following an END= exit cancels the incrementation.
(b) Given a combined stream and file number of the form N = 1000*nn+fff where nn is in the range 1 to 99 and fff lies in the range 0 to 999, then
CALL GETDD (N,DDNAME)
will return the ddname corresponding to file fff of stream nn, i.e. FTnnFfff
(c) CALL GETDD (STRING,DDNAME)
will copy up to eight characters from STRING into DDNAME. The first blank in STRING terminates the copy and DDNAME is padded with blanks where necessary. STRING must accommodate either 8 characters or sufficient to include the blank. Example
CALL GETDD ('SYSIN ',DDNAME)
will put SYSIN followed by three blanks into DDNAME.
(i) N out of range: -16777216 < N <1, 50 < N < 1000 or N > 50000, DDNAME is returned as eight zero bytes i.e. 0.0D0.
(ii) N < -16777215, the subroutine will treat N and the the word following N as though it defined an area to be used as in usage
(c). Thus up to 8 bytes could be copied into DDNAME from N and the following location.
IBM 360 Assembler.
GETDD is a subroutine with two arguments. The first argument may be either (a) an Integer, or (b) an area containing a character string of eight non-blank bytes, or (c) an area containing a character string of less than eight bytes but including at least one blank. GETDD refers to the Fortran Data Set Assignment Table IFYUATBL.
GETDD is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
P J Hemmings
Several of the Fortran callable dataset handling routines require work areas for use as standard OS control blocks. In order to avoid duplication when more than one such routine is used, a control block (which may be used like a labelled common block) has been created called D$ETUP.
D$ETUP is not executable. Assembler programmers may define the internal organisation of the control block by use of the Rutherford Macro D#SETUP. (See write-up of SYS1.RHELMAC).
IBM 360 Assembler.
D$ETUP is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
C D Osland
A description of the organisation of the control blocks is provided when the Macro D#SETUP is invoked by the Assembler unless the NOGEN option is in force.
The type of unit and device on which a dataset resides may be determined by function IDVICE. A crude distinction between readers/ printers/ disks etc. may be made, and in addition the specific device type (e.g. which model of 3330) may be found. In the following examples, assume the following declarations:
REAL*8 DDNAME/'FTOIFOOI'/
INTEGER*4 ISTRM
INTEGER*2 IBMTYP,IZUNIT
(a) IT = IDVICE(DDNAME) or IT = IDVICE(ISTRM)
This call to function IDVICE will set 'IT' to one of the following values:
-3 invalid DDNAME or ISTRM value -1 'DDNAME' not specified in JCL 0 DUMMY dataset declared in JCL 1 card reader 2 lineprinter 3 card punch 4 moving head disk 5 fixed head disk (drum) 6 tape (9 track) 7 tape (7 track) 8 communication device 9 any valid but unclassified device
Note that value -3 should never occur - it indicates a system error, and should be reported to User Support Group at Rutherford.
(b) IT = IDVICE(DDNAME,IBMTYP) or IT = IDVICE(ISTRM,IBMTYP)
As for example (a), and in addition 'IBMTYP' will be set to bytes 3 & 4 of the 'UCBTYP' field for the device associated with the dataset. Possible values are:
IBMTYP = X'2009f for model 1 3330 disk
X'200B' for 3350 disk
X'200D' for model 11 3330 disk
X'200E' for 3380 disk
See the reference for the possible values of these bytes.
(c) IT = IDVICE(DDNAME,IBMTYP,IZUNIT) or IT = IDVICE(ISTRM,IBMTYP,IZUNIT)
As for example (b), and in addition 'IZUNIT' will be set to the IBM all-digit name of the device in hexadecimal e.g. IZUNIT = X'3330' if device is 3330 disk, but note that this does not distinguish between model 1 and model 11.
If the routine is used with a 'ddname' for which concatenated datasets are specified, the values returned are those for the first DD card. If the value returned by the function is not positive, parameters 'IBMTYP' and 'IZUNIT' will not be altered. The routine is not restricted to Fortran style datasets (ie FTnnFmmm). The parameter ISTRM uses the same convention as for routine GETDD(SY/21).
IBM 360 Assembler.
IDVICE is an integer function with one to three arguments. The first is a full word integer or an eight character string of any type. The second and third arguments are half-word integers. IDVICE calls routine GETDD (SY/21).
IDVICE is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
OS/VS2 Debugging Handbook Volume 3 GC28-1049
C D Osland
This subroutine makes a ddcard refer to a different data set during the execution of a program, provided that the required data set is on the same VOLUME as the previous data set (if you wish to switch VOLUME as well, then you should use SERLAB (SY/25)). The DCB information of the switched data sets must be the same.
Neither the original nor the substituted data sets may be DUMMY (i.e. DSN=NULLFILE).
If the stream or ddname is already Open, then SETDSN will perform a Close operation and in the case of Fortran data sets revert to the ddname FTxxFOO1.
(i) CALL SETDSN (1,'RUN42 ')
(ii) CALL SETDSN ('SYSUT2 ','USER.ID1 ')
(iii) LOGICAL*1 DSN4(44)/'THIS.DSNAME '/
CALL SETDSN (3,DSN4)
(iv) CALL SETDSN (8013,'FILE13 ')
are examples of the general form
CALL SETDSN (stream, data-set-name)
(1) stream is one of the following:
(a) a Fortran Integer in the range 1 to 50 denoting stream number;
(b) a Fortran Integer equal to nn*1000 + fff where nn is a stream number in the range 1 to 50 and fff is a file number in the range 1 to 999;
(c) an eight character ddname; (d) a shorter ddname terminated by a blank.
(2) data-set-name is one of:
(e) a 44-character data set name;
(f) a shorter data set name terminated by a blank.
A User ABEND 57 is issued in the following three cases:
(a) Stream number is not valid;
(b) The original data set is DUMMY;
(c) No DD card has been provided in the JCL.
Other errors:
(d) requesting a non-existent or DUMMY data set causes 813, 013 ABENDs;
(e) other erroneous requests will cause other ABENDs.
IBM 360 Assembler.
SETDSN is a subroutine called with two arguments. SETDSN calls GETDD (SY/21) and CLFILE (SY/26) and accesses the control block D$ETUP (SY/22).
SETDSN is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
T Noland with extensive modifications by P J Hemmings.
This subroutine may be used to change tapes and/or files, and optionally data set names during the execution of a program without having to supply a DD card for each file of each tape used. The subroutine may also be used to switch demountable disks with or without a change of data set name.
It is not permitted to change for example a 9-track for a 7-track tape, or a data set on tape for a data set on disk. The UNIT parameter must be the same for both data sets. In particular neither data set may be DUMMY. A further restriction is that in the case of disk data sets, a permanently resident disk may not be switched in or out.
Unless both data sets are on the same permanently mounted disk, then the tape (or disk) names must appear in the JCL. See 'Volume Setup' below.
It is permitted to switch to NL, BLP or SL for type of Label. None of the DCB information such as RECFM, LRECL, BLKSIZE or expiry date may be changed.
If the ddname is a Fortran stream, then SERLAB will perform the close operation before doing the requested switch. Fortran streams will revert to the ddname FTxxFOOl.
(i) CALL SERLAB (1,'901234',3)
(ii) CALL SERLAB ('FT02F001','777777',5,1)
(iii) REAL*8 VOLUME /'900000'/
CALL SERLAB (2,VOLUME,1,0,'BLP1)
(iv) CALL SERLAB (N,0,I,1,'DSN=ABC ')
(v) CALL SERLAB (N,0,I,1,'ABC ')
(vi) CALL SERLAB ('SYSUT3 ','900000',1)
(vii) CALL SERLAB (5,'777777')
The above are all examples of the general form
CALL SERLAB (stream, volume, file, mode, label-type or data-set-name)
(1) Stream is one of:
(a) a Fortran Integer denoting stream number;
(b) an eight character ddname;
(c) a shorter ddname terminated by a blank.
(2) Volume is one of:
(d) a six character volume serial number;
(e) a Fortran zero indicating no change of tape or disk.
The remaining arguments are optional but may only be omitted if default values are also to be assumed for all subsequent arguments.
(3) File is:
(f) a Fortran Integer denoting physical file on the tape (Default value of file is 1);
(4) Mode is a Fortran Integer:
(g) 0 denotes an input stream?
(h) 1 denotes an output stream (default is 0 for OLD datasets and 1 otherwise).
(5) The last parameter is either a label-type or a data-set-name. Label-type is one of the character strings:
(j) SL
(k) BLP
(l) NL
Data-set-name is one of:
(m) a 44 character data set name;
(n) a shorter data set name terminated by a blank;
(o) form (m) or (n) prefixed by 'DSN='.
MVS needs to be told about every volume to be set up during a job before the job executes. This is so that it can make sure that all the volumes needed are available. If a job attempts to mount a tape that is not defined in its JCL then it will be cancelled. In the following example four tapes are to be read from Fortran stream one.
//ANY JOB (ACCT,ID),PASSWORD=SECRET // EXEC JOBLIB, // LIBRARY='OURNODE.LOADLIB', // MEMBER=MANYTAPE //G.FT01F001 DD DSN=RUN01.DATA, // VOL=SER=900001f // UNIT=DEN6250, // LABEL=(1,SL,,IN), // DISP=OLD //TAPE2 DD DSN=RUN02.DATA, // VOL=SER=900002, // UNIT=AFF=FT01F001, // LABEL=(1,SL,,IN), // DISP=OLD //TAPES DD DSN=RUN03.DATA, // VOL=SER=900003, // UNIT=AFF=FT01F001, // LABEL=(1,SL,,IN), // DISP=OLD //TAPE4 DD DSN=RUN04.DATA, // VOL=SER=900004, // UNIT=AFF=FT01F001, // LABEL=(1,SL,,IN), // DISP=OLD
SERLAB can be called to select any of the tapes 900001, 900002, 900003, 900004, during the execution of the programme. The actual ddnames TAPE2, TAPE3 and TAPE4 are unimportant. The unit parameter should be given as UNIT=AFF=ddnamel, where ddname1 is the name of the stream on which the tape will be used.
The call to SERLAB is ignored under any of the three following conditions:
(a) stream number not in the range 1 to 99;
(b) the original data set is DUMMY;
(c) no DD card provided in the JCL.
Other possible errors are:
(d) the mode parameter is neither 0 nor 1 - SERLAE assumes a request to input;
(e) incorrect volume, file or data set name when using Standard Labels - an 813 ABEND will occur with tapes and a 213 ABEND with disks;
(f) requesting or implying a non-existent file number (e.g. asking for file 7 when there are only 3 on the tape) - a 613 ABEND will occur;
(g) other incompatible or erroneous requests lead to other ABENDs.
IBM 360 Assembler.
SERLAB is a subroutine called with two, three, four or five arguments as described above. SERLAB calls the subroutines GETDD (SY/21) and CLFILE (SY/26) and accesses the control block D$ETUP (SY/22).
SERLAB is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
T Noland with extensive modifications by P Day and P J Hemmings.
(a) CALL CLOSET ('FT06F001')
(b) REAL*8 DDNAME/'FT06F001'/
CALL CLOSET (DDNAME)
If the data set is Open, it will be closed. If it is not Open (because it was never used), nothing happens. If no JCL was provided nothing happens either.
CLOSET is not normally appropriate for Fortran data sets as it does not empty (for output streams) or free buffer areas. These operations are performed by CLFILE (SY/26) which should normally be used instead.
IBM 360 Assembler.
CLOSET is a subroutine called with one argument which is a character string of eight bytes. No subsidiary routines are required.
CLOSET is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
P D Day
This routine examines the JCL associated with a given Fortran stream number or ddname. In the case of tapes both VOLUME and FILE are meaningful, but the user should appreciate the difference between the physical file on tape (given by the LABEL parameter in the JCL) and the File Number read by a program, e.g. FT01F001, FT01F002, FT01F003 are the ddnames of the first three files to be used by stream 1 and these files need not be on the same volume or even have the same device type.
Optionally, the expiry date may be returned as an Integer of the form 1000*year+day e.g. 86009.
WARNING - in the case of multivolume data sets, or if two data sets are concatenated TFILAB returns the first VOLUME and FILE regardless of any subsequent volume switch.
(i) REAL*8 VOLUME
CALL TFILAB (1,VOLUME,NFILE)
(ii) INTEGER*2 VNAME(3)
CALL TFILAB ('SYSUT2 ',VNAME,NFILE)
(iii) LOGICAL*1 VOL(6)
INTEGER EXPDT
CALL TFILAB (3,VOL,IFL,EXPDT)
(iv) LOGICAL*1 VOL(6)
CALL TFILAB (8013,VOL,NFILE)
are examples of the general form
CALL TFILAB (stream, volume, file, expiry-date)
(1) stream is one of the following:
(a) a Fortran Integer in the range 1 to 50 denoting stream number;
(b) a Fortran Integer equal to nn*1000 + fff where nn is a stream number in the range 1 to 99 and fff is a file number in the range 1 to 999;
(c) an eight character ddname;
(d) a shorter ddname terminated by a blank.
(2) volume is a variable or an array capable of accommodating a six byte character string
(3) file is an Integer.
(4) expiry-date is an Integer.
In the following cases:
(a) Stream number is not valid
(b) The original data set is DUMMY
(c) No DD card has been provided in the JCL the volume is returned as six blanks and file will be returned as zero or a number given in the LABEL field of the DD card.
IBM 360 Assembler.
TFILAB is a subroutine having four arguments, the fourth of which is optional. TFILAB calls GETDD (SY/21) and CLFILE (SY/26) and accesses the control block D$ETUP (SY/22).
TFILAE is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
T Noland with modifications by P J Hemmings and J C Hart.
This routine changes the member name of a partitioned data set associated with a given ddname or Fortran stream. The JCL must refer to the member of a partitioned data set e.g. DSN=NAME(MEMBER1). This subroutine may be used to change the member name but not the data set name.
(i) CALL CHJFCB (1,'MEMBER2 ')
(ii) CALL CHJFCB ('FT02F001','ABC ')
(iii) REAL*8 XYZ/'A123'/
CALL CHJFCB ( N,XYZ )
are examples of the general form
CALL CHJFCB (stream,member)
(1) Stream is one of:
(a) a Fortran Integer in the range 1 to 50 denoting stream number;
(b) a Fortran Integer equal to nn*1000 + fff, where nn is a stream number in the range 1 to 50 and fff is a file number in the range 1 to 999;
(c) an eight character ddname;
(d) a shorter ddname terminated by a blank.
(2) Member is one of:
(e) an eight character member name;
(f) a shorter member name terminated by a blank.
Calls to CHJFCB are ignored under any of the following conditions:
(a) Stream number is not valid;
(b) The original data set is DUMMY;
(c) No DD card has been provided in the JCL.
Other possible error:
(d) the member does not exist - attempts to read from the stream will cause an 013 ABEND.
IBM 360 Assembler.
CHJFCB is a subroutine having two arguments. CHJFCB calls GETDD(SY/21) and IBCOM and accesses the control block D$ETUP(SY/22).
CHJFCB is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
T Noland with modifications by P J Hemmings.
This routine changes the JCL associated with a given Fortran stream number or ddname. If you wish to append to a data set without overwriting, you can dynamically set DISP=MOD. In particular, it is necessary after a REWIND or a CALL CLFILE(SY/26) or CLOSET(SY/27).
(i) CALL DSPMOD(3)
(ii) CALL DSPMOD ('FT02F001')
are examples of the general form
CALL DSPMOD (stream)
(1) stream is one of:
(a) a Fortran Integer in the range 1 to 99 denoting stream number;
(b) a Fortran Integer equal to nn*1000 + fff nn is a stream number in the range 1 to 99 and fff is a file number in the range 1 to 999;
(c) an eight character ddname;
(d) a shorter ddname terminated by a blank.
The call to DSPMOD is ignored in the following three cases:
(a) Stream number is not valid;
(b) The original data set is DUMMY;
(c) No DD card has been provided in the JCL.
IBM 360 Assembler.
DSPMOD is a subroutine having one argument. DSPMOD calls GETDD(SY/21) and CLFILE(SY/26) and accesses the control block D$ETUP(SY/22).
DSPMOD is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
T Noland with modifications by P J Hemmings.
Consider the situation where two jobs might simultaneously attempt to update the same record in a data set. Normally one guards against this by using DISP=OLD to ensure that Job steps do not run simultaneously, but this is not always possible or appropriate.
There is a mechanism which allows programmers to associate a name with a group of code sequences. Before executing a code sequence which belongs to such a group, one can inform the system that you wish to use the group name. If the name is not already in use, the system gives a normal return. Otherwise a non-zero return code or ABEND is given according to how the system was called.
The choice of group name (which the system terms a Resource) is for private agreement between the programmers involved but should obey the local rules for Data Sets. The name must be eight characters long, padded with blanks where necessary.
The routines ENQ and DEQ make use of this mechanism. Generally it is used to preserve the integrity of a data set, but it could be used for other purposes such as improving efficiency of input or output.
CALL ENQ ('abcdefgh',NETCOD)
IF (NETCOD .NE. 0) GO TO 100
READ (1'M) RECORD
CALL MODIFY (RECORD)
WRITE (1'M) RECORD
CALL DEQ ('abcdefgh',NETCOD)
IF (NETCOD .NE. 0) GO TO 101
(a) ENQ may be used as follows:
CALL ENQ ( RESRCE )
or CALL ENQ ( RESRCE,NETCOD )
or CALL ENQ ( RESRCE,NETCOD,&L1,&L2 )
RESRCE is an eight byte character string being the agreed name of the Resource, i.e group of code sequences. When the argument NETCOD is in the calling sequence it will be set to one of the following values:
NETCOD=0 indicating the Resource is yours;
NETCOD=4 the Resource is being used by another job;
NETCOD=8 you already have the resource and have not returned it to the system (by DEQ).
If the arguments &L1 and &L2 are given, then return will be to statements numbered L1 and L2 when NETCOD = 4 or 8 respectively. When the argument NETCOD is not in the calling sequence, and the Resource cannot be given to you, your program will be terminated with ABEND 138.
(b) DEQ is used as follows:
CALL DEQ ( RESRCE)
or CALL DEQ ( RESRCE,NETCOD )
or CALL DEQ ( RESRCE,NETCOD,&L1,&L2)
are the corresponding calls for releasing the Resource. In this case NETCOD is returned as follows:
NETCOD=0 is the normal return;
NETCOD=4 your program has independently issued the ENQ macro and has not yet been given the Resource;
NETCOD=8 no previous ENQ has been issued, or a DEQ has already been obeyed.
If only one argument is given, NETCOD = 4 or 8 are replaced by ABEND 130 and 530 respectively.
IBM 360 Assembler.
ENQ is a subroutine which has DEQ as a second entry. Each may have one or two arguments. (Note that the non-standard returns &L1 and &L2 do not count as arguments.) The first argument which is an eight byte character string must be present. The second argument if present must be an Integer.
ENQ with DEQ is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
T Noland
IBM 360 Assembler.
... are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
Routine STIMER puts the calling program into a WAIT state for N l/100ths of a second.
CALL STIMER ( N ) where N > 0
calls upon the supervisor to place the calling program (task) into a WAIT state for N hundredths of a second. If N < 1, the call is ignored.
IBM 360 Assembler.
STIMER is a subroutine with one Integer*4 argument. No subsidiary routines are required.
STIMER is stored stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
C S Cooper
REAL*8 DDN
INTEGER*4 I
I = IDUNIT (DDN)
sets I to A3 (EBCDIC) unit name plus 1 padding blank. DDN is a REAL*8 variable 8 byte field containing the ddname to be found. It must be left adjusted and padded with trailing blanks if necessary. For example:
I = IDUNIT('FT01F001')
with
//G.FT01F001 DD UNIT=DEN6250
could return I as '286 ', but this value would depend on the tape drive used.
DD card is not found or DUMMY returns the value ' ', i.e. four blanks.
The unit for a Fortran Stream can be found if the stream number is first converted to a DDname using GETDD (SY/21).
IBM 360 Assembler.
C D Osland
CALL JPNAME(JOB,PGM)
where JOB and PGM are REAL*8 variables, or any arrays with a total length of 8 bytes, returns the job and program names. If these are less than 8 characters long they are left adjusted and padded with blanks.
The program name is the load module name for a program executed from a library (e.g. using the JOBLIB procedure). For Fortran programs this defaults to 'MAIN'.
IBM 360 Assembler.
JPNAME is a subroutine. No subsidiary routines are called.
JPNAME is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
J C Hart
CALL STOP(N)
terminates execution of a program and sets the condition code to N, where N is any integer constant, variable or expression in the range 0 <= N <= 32767. N.B. In the Fortran statement STOP n, n must be an integer constant.
If N lies outside the given range, the stop code is obtained by taking the absolute value of the integer represented by the low order 16 bits of N.
IBM 360 Assembler.
STOP is a subroutine. Control is passed to the Fortran library routine IBCOM#.
STOP is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
J C Hart
CALL BLKCNT ( ITAPE, NBLK, LBLK, IDEN, &error )
where ITAPE is the Fortran stream number of an input or output, tape returns NBLK as the number of physical blocks currently read or written to tape, LBLK as the block, size and IDEN as the density code, provided the data set is open. (This means that a READ or WRITE statement has been executed and the data set has not been closed by a REWIND statement or by a call to CLFILE or SERLAB.)
The first argument may be an 8-byte DDNAME instead of a Fortran stream number, e.g.
CALL BLKCNT ( 'FT10F001', NBLK, LBLK, IDEN) )
This case is recognized by the fact that the first byte of the first argument is non-zero.
The last two arguments are optional; either IDEN or both LBLK and IDEN may be omitted. The density codes returned are:
0 1 556 bpi 2 800 bpi 3 1600 bpi 4 6250 bpi
Following an error, control is returned to the statement indicated by '&error' if it is present, and NBLK is set to a negative value as follows:
NBLK ERROR -1 Fortran stream number > 99 given -2 Fortran stream not in use (not open) -3 Data set is direct access -4 Data set is not magnetic tape -5 DDNAME given, but DCB not found -(perhaps not open) -6 DDNAME given and DCB found but not open
IBM 360 Assembler.
BLKCNT is a subroutine. No subsidiary subroutines are called.
BLKCNT is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
J C Hart
Routine MVSID returns the identification of the machine on which the job that calls MVSID is running (i.e. 3032 or 3081 or 3033 for Atlas10).
CALL MVSID(N)
N will be set to 3033 or 3081 after the call. This value may be tested for in a Fortran IF statement etc.
IBM 360 Assembler.
MVSID is a subroutine with one Integer*4 argument. No subsidiary routines are required.
MVSID is in the Automatic Call Library. It is available in CMS.
D F Parker and modified for MVS by C P Wood.
INDUSE returns the values available from the CP INDICATE USER command which is fully described in the CP Command Reference manual.
INTEGER IVALUE(12)
CALL INDUSE (IVALUE)
sets
IVALUE(l) to VTIME : Virtual CPU time in milliseconds
IVALUE(2) to TTIME : Total CPU time in milliseconds
IVALUE(3) to RDR total : Virtual cards read
IVALUE(4) to PRT total : Virtual lines printed
IVALUE(5) to PUN total : virtual cards punched
IVALUE(6) to SIO total : non-spooled I/O requests
IVALUE(7) to RES PAGES : number of pages in main storage
IVALUE(8) to WS PAGES : number of active pages
IVALUE(9) to PAGE READS : page reads so far
IVALUE(10) to PAGE WRITES : page writes so far
IVALUE(11) to DISK PAGES : pages on moving head disk
IVALUE(12) to DRUM PAGES : pages on fixed head disk
IBM 360 Assembler.
INDUSE is a subroutine with no additional entry points. It requires a single argument which should be a 12 element Integer*4 array. No subsidiary subroutines are required.
INDUSE is only available in CMS.
C D Osland
This routine returns the Userid of a job executing in MVS.
(a) INTEGER IUS(2)
CALL USERID (IUS)
or
(b) CHARACTER* N USID
CALL USERID (USID)
Option (a): This call returns an eight byte character string in IUS which is the USERID padded with any necessary trailing spaces. If the USERID is found to be more than 8 characters long then the first 8 characters will be returned.
Option (b): (N is any number defining the length of the character string .) If the USERID has X characters, where X is less than or equal to N, then X characters will be moved into the character string followed by (N-X) trailing spaces.
If the USERID has X characters, where X is greater than N then the first N characters will be moved into the character string.
If no USERID can be found the calling program will ABEND with a System code of 2EF (this should never happen...if it does inform PAD).
IBM 360 Assembler.
USERID is a subroutine with one entry point. No subsidiary routine is required.
USERID is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is not available in CMS.
M M Curtis
These two routines obtain from the TDMS subsystem last use information for a given TAPE volume. This information is updated each time a volume is successfully opened and is provided by the security system ACF2. Both routines return the time and date of the open as well as the name of the job opening the volume. In addition routine TDMSWU will provide the caller with the sequence number of the last file written on the tape, under MVS.
Routine TDMSWU returns last write information. Routine TDMSRU returns last read information.
INTEGER*4 RC,TIME(3),DATE(3),FILE
CHARACTER VOLUME*6,JOBNAME*8
CALL TDMSWU(RC, VOLUME, JOBNAME, TIME, DATE, FILE)
CALL TDMSRU(RC, VOLUME, JOBNAME, TIME, DATE)
Where:
RC on return will contain the return code from the routine, this indicates the success of the call. See below for description.
VOLUME is the name of the volume that is being inquired upon.
JOBNAME is returned and is the name of the job that last accessed the volume.
TIME is returned and contains the time the volume was last opened. TIME(1) contains the hour, TIME(2) contains the minute and TIME(3) contains the seconds.
DATE is returned and contains the date the volume was last opened. DATE(1) contains the day, DATE(2) contains the month and DATE(3) contains the year.
FILE is returned only when last write information is requested (TDMSWU) and contains the file sequence number of the file last opened for write.
Return codes:
0 Success, all fields filled in.
1 Volume specified is unknown to TDMS.
2 Volume specified is non TAPE. Usage information is not kept for DASD volumes.
104-112 Communication with TDMS temporarily impossible, should be available shortly.
116-144 Permanent failure of communication with TDMS.
204-212 Communication with TDMS temporarily impossible, should be available shortly.
Occurs during data acquisition.
216-244 Permanent failure of communication with TDMS during data acquisition.
Other A failure has occurred in the TDMS subsystem while
processing your request, the actual return code corresponds to a PL/I error code.
IBM Assembler. These routines can be called from either FORTRAN (66 or 77) or PL/I with options ASSEMBLER.
These two routines are purely an interface between the user and module VMFUSE which is responsible for communication with TDMS. As module VMFUSE is loaded the user must ensure that 4Kb of storage is available at the time of call to either TDMSWU or TDMSRU, and that he does not have a module named VMFUSE in any private program library accessible at the time of call. This method is employed so changes to VMFUSE or the format of the data will not result in the need to re-linkedit all programs that use this facility.
(1) The time and date returned are always GMT values. This is due to the way the time is obtained from the system.
(2) Last read data when using FORTRAN. FORTRAN always opens its datasets with the attribute INOUT, regardless of the type of operations to be performed on the dataset. This ambiguity causes TDMS to record the open as one for WRITE. The way to overcome this problem is to code the IN parameter in the LABEL field of the DD statement that relates to the file being opened, the file is then opened for read only and TDMS records this accordingly.
(3) If the volume has not been used under MVS the values returned will be - FILE=0, DATE(1)=1, DATE(2)=1, DATE(3)=0, TIME(1)=0, TIME(2)=0, AND TIME(3)=0.
C A Wilkins
These routines provide the user with the ability to store and manage certain records within the TDMS database that are related to a specific volume. The contents of these records is user defined, no processing is done on them by any other part of the TDMS system.
Two record types are made available to the user, a COMMENT record and a USER record. No control is made over what type of information can be stored within the record. The only restriction is that the TDMS listing facilities may provide more formatting control over a COMMENT record.
Six routines are provided to allow access to the records, they are:
TDMSDU deletes a user record from the TDMS database.
TDMSPU writes a user record into the TDMS database.
TDMSGU reads a user record from the TDMS database.
TDMSDC deletes a comment record from the TDMS database.
TDMSPC writes a comment record into the TDMS database.
TDMSGC reads a comment record from the TDMS database.
INTEGER*4 RC,LEN
CHARACTER VOLUME*6,DATA*500
CALL TDMSDU(RC,VOLUME)
CALL TDMSPU(RC,VOLUME,LEN,DATA)
CALL TDMSGU(RC,VOLUME,LEN,DATA)
CALL TDMSDC(RC,VOLUME)
CALL TDMSPC(RC,VOLUME,LEN,DATA)
CALL TDMSGC(RC,VOLUME,LEN,DATA)
where
RC on return will contain the return code from the routine called, this indicates the success of the call. See below for full description.
VOLUME is the name of the volume for which the call relates.
LEN is the length of the data to be transmitted. On return from the GET routines (TDMSGC and TDMSGU) this will contain the actual length of the data acquired from TDMS. Currently the maximum length of the data that can be stored in TDMS is 500 bytes.
DATA is the source or the target area for data transmission.
Return codes:
0 Required function completed successfully.
1 Record requested does not exist.
2 Volume to which this record is to be associated does not exist.
10 Source data area is too long (as indicated by LEN). Maximum size is 500 bytes.
104-112 Communication with TDMS temporarily impossible, should be available shortly.
116-144 Permanent failure of communication with TDMS.
204-212 Communication with TDMS temporarily impossible, should be available shortly. Occurs during data acquisition.
216-244 Permanent failure of communication with TDMS during data acquisition.
2xxxx Target area for data read is not long enough for the data in the record,
xxxx bytes is the length required.
Other A failure has occurred in the TDMS subsystem while processing your request,
the actual return code corresponds to a PL/I error code.
IBM 360 Assembler. These routines can be called from either FORTRAN (66 or 77) or PL/I with options ASSEMBLER.
These six routines are purely an interface between the user and module VMFUSR which is responsible for communication with TDMS. As module VMFUSR is loaded and deleted by these routines the user must ensure that 4Kb of storage is available at the time of the call and that he does not have a module named VMFUSR in any private program library accessible at the time of call. This method is employed so changes to VMFUSR or the format of the data will not result in the need to re-linkedit all programs that use this facility.
TDMS does not provide any mechanism to serialise access to the COMMENT or USER records. To ensure data integrity within these records you must implement a mechanism within your own programs, You are referred to the routine ENQ from the Rutherford program library.
C A Wilkins
This routine returns the account of a job or online session.
CHARACTER*N ACCNT
INTEGER*4 LENGTH
CALL GETACT(ACCNT, LENGTH)
The accounting field is moved into the string ACCNT. If specified LENGTH is set to be the number of characters set by GETACT. If the string ACCNT is not long enough to contain the whole of the field then only N leading characters are copied. In MVS the accounting field is a 17 byte string with the format:
aaaaaaaa-ssssssss
where aaaaaaaa = full ("parent") account number
the character '-' used as a delimiter
ssssssss = subproject number
Note that we have allowed up to 8 bytes for account and subproject, although in practice not all 8 bytes are used. In CMS the accounting field is up to 8 characters long. If no accounting information can be found the calling program will issue a message and return a length of zero.
IBM 360 Assembler.
GETACT is a subroutine with one entry point. No subsidiary routine is required.
GETACT is stored stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
M Ellwood. / A Banks.
Introduction: This routine extracts numeric and textual data from the MVS accounting database.
CALL GETSAM(IRC, NODE, FIELD1, VALUE1, FIELD2, VALUE2,........)
There are two fixed arguments followed by a variable number of pairs of arguments. IRC is an integer variable into which GETSAM will place a return code (see below for values).
NODE is a character expression which evaluates to the name of the node in the MVS database to be interrogated. NODE is passed to GETSAM.
FIELD1, FIELD2, etc. are character expressions which evaluate to the names of fields in the MVS database. These arguments are passed to GETSAM.
VALUE1, VALUE2, etc. are arguments returned by GETSAM. There can be any number of FIELD VALUE pairs but the type of VALUE depends on the field interrogated. Fields can have values of type
CHARACTER (eg. GROUPREP) REAL (eg. MVSWM) INTEGER (eg. GRNTLFT) BINARY (eg. GRNTFLG)
Binary fields are 1 bit flags which are returned to the caller as an integer having the value either 1 or 0. The sizes of the fields passed to the routine by the caller are optional. ACCT node and field names are all 8 character fields. If the caller passes longer fields they will be truncated on the right. If he passes shorter ones they will be padded on the right with spaces. No warning is given in either case.
Example:
CHARACTER REP*8,NODE*8
REAL WM
NODE='ABC'
CALL GETSAM(IRC,NODE,'MVSWM1,WM,'GROUPREP',REP)
IF(IRC.GT.O) PRINT*,'RETURN CODE FROM GETSAM=',IRC
Successful return codes:
0 all values returned and none truncated -1 all values returned at least one truncated
Unsuccessful return codes - no values returned:
1 wrong number of arguments
2 field name invalid or unsupported type
3 ACCT communication failure - bad ecb code
4 ACCT subsystem inactive
5 ACCT subsystem not running
8-99 other subsystem error codes. The only ones worth mentioning are 8 and 12,
which are temporary subsystem problems.
100+ a large number of ACCT error codes. The only ones of interest are
100 node not in database
108 database not available - ACF2 not running
Abends:
U100 unsupported linkage convention
GETSAM assumes VS Fortran linkage conventions (Release 3.0 and later) and can only be called from a Fortran program compiled with the VS Fortran Compiler (Release 3.0 or later) or an assembler program which follows these conventions.
IBM 370 Assembler.
GETSAM is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures.
A Mayhook
This routine uses subroutine GETSAM to return the number of AUS a subproject has left before it reaches its working maximum.
CALL GETAUS(IRC, NODE, AUS)
IRC contains the return code from GETSAM. NODE is a character expression containing the name of the subproject. AUS contains the number of AUS left (MVSWM-MVSUSEDC-MVSQUEUE)
ISO FORTRAN 77 compiled using IBM VS Fortran compiler
GETAUS is a subroutine with one entry point. The subsidiary routine GETSAM is required.
GETAUS is stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. It is available in CMS.
J Gordon
Associated with each program there are four bits in the Program Status Word called the Program Mask. These bits enable (when 1) or disable (when 0) program interruptions due to: fixed-point overflow; decimal overflow; floating-point exponent underflow; and significance exceptions. The meaning of these interruptions, and how the arithmetic process completes, is described in the "Principles of Operation" Manual.
The Fortran default setting is to enable only exponent underflow interruptions. IBM provide a routine called XUFLOW as a 'Service and Utility' subroutine (described in chapter 9 for the Fortran Language Reference) to change the value of the exponent underflow mask. These routines complement the IBM routine and allow the testing and setting of all the masks.
The divide and exponent-overflow exceptions cannot be disabled in this way, however, routines DVCHK and OVERFL (also described in chapter 9 for the Fortran Language reference) allow one to test the existence of these conditions.
(a) CALL DEOVER(intvar)
where intvar is an INTEGER*4 variable with the value 1 or 0. When intvar is zero, decimal overflows are disabled. When intvar is non zero, decimal overflows are enabled.
(b) CALL FPOVER(intvar)
where intvar is an INTEGER*4 variable with the value 1 or 0. When intvar is zero, floating point overflows are disabled. When intvar is non zero, floating point overflows are enabled.
(c) CALL SIGNIF(intvar)
where intvar is an INTEGER*4 variable with the value 1 or 0. When intvar is zero, significance exceptions are disabled. When intvar is non zero, significance exceptions are enabled.
(d) CALL QXUFLO(intvar)
where intvar is an INTEGER*4 variable which is returned. When intvar is returned as zero, exponent underflow exceptions are disabled. When intvar is returned as one, exponent enderflow exceptions are enabled.
(e) CALL QFPOVE(intvar)
where intvar is an INTEGER*4 variable which is returned. When intvar is returned as zero, floating point overflow exceptions are disabled. When intvar is returned as one, floating point overflow exceptions are enabled.
(f) CALL QSIGNKintvar)
where intvar is an INTEGER*4 variable which is returned. When intvar is returned as zero, significance exceptions are disabled. When intvar is returned as one, significance exceptions are enabled, display begin flow
(g) CALL QDEOVE(intvar)
where intvar is an INTEGER*4 variable which is returned. When intvar is returned as zero, decimal overflow exceptions are disabled. When intvar is returned as one, decimal overflow exceptions are enabled.
IBM OS/VS-VM/370 Assembler.
DEOVER, FPOVER, SIGNIF, QXUFLO, QFPOVE, QSIGNI and QDEOVE are separate subroutines, each of which has an Integer argument. No subsidiary routines are required.
All are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
A Banks
The SYSREQ facility represents a family of commands which can be used to pass commands to, and receive replies from, system services which run in disconnected virtual machine servers. The command has been implemented, and has the same structure, in a number of operating systems. It is available in each of these systems, as a base level command (or procedure) and also as a FORTRAN callable subroutine. The latter are documented here.
These routines provide a means of performing a system-wide service function, without the need to know where the server program is or the means of communicating with it.
INTEGER*4 RCODE,ARYSZ
CHARACTER*8 SERNAM , CHARACTER*120 COMTXT , CHARACTER*80 REPTXT(dim)
CALL SYSREQ(SERNAM, COMTXT, RCODE, REPTXT, ARYSZ)
SERNAM Character variable set, on entry, to the name of system service required. May be up to 8 characters, and will be truncated if greater.
COMTXT Character variable set, on entry, to the text of the command which is to be passed to the system service. May be up to 120 characters, and will be truncated if greater.
RCODE Is the return code from the subroutine call. Set on return, to the value of the return code set by the completion of the system service command (if the call completed successfully), or to the return code from the service call procedure (if the call did not complete).
When RCODE is non-zero there is usually at least one line of associated error text, in the REPTXT array.
REPTXT Character array, set on return, into which the routine places the reply from the system service (or an error message if the call did not complete). The reply text is returned as one line of text per element of the array. The dimension of the array (dim) should be at least as large as the maximum number of lines returned by the command, else only the number available will be returned and an error code set.
If the lines returned are too long for the *type of the array elements then the lines are folded across multiple elements.
ARY5Z Integer variable which must be set on entry to the dimension of the array into which the reply is to be returned. If it is set to less than dim, then only ARYSZ lines will be returned; if it is set to more than dim, then your program will abend with a storage overwrite.
On return, ARYSIZ is set to the number of array elements which have been filled with returned data.
Return codes:
0 Successful call. Service command successfully completed.
1 Not used.
2 Insufficient space to return all the reply data from the system service.
Only ARYSIZ lines have been returned.
3 Unknown system service name.
Other Return codes set by the system service (if call completed but service
command in error), or by the service call procedure (if the call failed).
IBM 360 Assembler. This routine can be called from FORTRAN (66 or 77, although 77 is the recommended interface); or PL/I with options ASSEMBLER; or assembler with a Fortran 77 plist convention.
The routine is self contained and re-entrant, all external references are resolved.
1) Declaration of variables
The declarations for the character type variables given above represent the maximum values that the routine will use as working values. The character * numbers may be made larger (in which case data beyond the values declared above is ignored, or not set) or smaller (in which case only this amount of data is transmitted to the system service, or returned data which overflows is wrapped into multiple array elements).
Thus the maximum length of text sent to a system service is 120 characters; the maximum length of a line returned by a system service is 80 characters.
2) Language Interface
If the routine is called from FORTRAN 66, then these values are assumed: 120 characters of information is always sent, and *number of the return array is always treated as 80. The REPTXT array should then be treated as REPTXT(80,n) where 80*n=(bytes per word)*ARYSZ. Clearly this can lead to storage problems, if the array is not of sufficiently large dimension, and so Fortran 77 is the recommended interface.
Jonathan Wood
The ACCT system controls accounting in VM/CMS, MVS and COS. Commands can be passed to ACCT from any of these systems to interrogate and/or control accounting in that system or in any of the others, eg the CMS interface to ACCT can be used to manipulate accounts for use of CMS or COS. Similarly, the COS interface can be used for CMS or COS accounts.
The ACCT routine in RHELIB allows a Fortran program in CMS, MVS or COS to send commands to the ACCT system.
This writeup only describes the ACCT Fortran-callable subroutine interface. The form of the commands passed to ACCT are described elsewhere. The particular commands that can be sent vary according to the privileges the user has in the ACCT system.
INTEGER*4 RCODE,ARYSZ
CHARACTER*8 SERNAM , CHARACTER*120 COMTXT , CHARACTER*80 REPTXT(dim)
CALL ACCT(COMTXT, RCODE, REPTXT, ARYSZ)
Where:
COMTXT Character variable set, on entry, to the text of the command which is to be passed to the ACCT system. May be up to 120 characters, and will be truncated if greater.
RCODE Is the return code from the subroutine call. Set on return, to the value of the return code set by the completion of the system service command (if the call completed successfully), or to the return code from the service call procedure (if the call did not complete).
When RCODE is non-zero there is usually at least one line of associated error text, in the REPTXT array.
REPTXT Character array, set on return, into which the routine places the reply from the system service (or an error message if the call did not complete). The reply text is returned as one line of text per element of the array. The dimension of the array (dim) should be at least as large as the maximum number of lines returned by the command, else only the number available will be returned and an error code set.
If the lines returned are too long for the *type of the array elements then the lines are folded across multiple elements.
ARYSZ Integer variable which must be set on entry to the dimension of the array into which the reply is to be returned. If it is set to less than dim, then only ARYSZ lines will be returned; if it is set to more than dim, then your program will abend with a storage overwrite.
On return, ARYSIZ is set to the number of array elements which have been filled with returned data.
Return codes:
0 Successful call. ACCT command successfully completed.
1 Not used.
2 Insufficient space to return all the reply data from ACCT. Only ARYSIZ lines have been returned.
3 Internal problem. Report to PAO.
Other Return codes set by ACCT if the ACCT system or the call made to it failed.
FORTRAN 77
The routine ACCT calls SYSREQ(SY/69).
... are stored in MVS library PROGLIB.RHELIB.LIBRARY. This library is automatically available to the linkage editor steps of the RAL Fortran and Assembler procedures. They are available in CMS.
See SYSREQ(SY/69) for a list of restrictions.
John Gordon
**********The original copies dating back to 1976 could not be OCR'd successfully*****************