PIGLET is a set of FORTRAN and PLASYD subroutines which accept as input a sequence of free format commands and pass control and arguments to matching applications procedures. Command syntax and argument retrieving procedures are identical to those used in the PDP15 Interactive Graphics System (PIGS). The PICS manual should be regarded as the major reference for this paper. Command names are associated with application procedures at run time using special FORTRAN subroutines.
Section 9 of this paper contains an example program (PIGTST) using PIGLET which has two commands:
PRINT,I,J /PRINT OUT VALUES OF ARRAY LOCATIONS I TO J
SCALE,FACTOR,I,J /SCALE ARRAY LOCATIONS I TO J BY FACTOR
As a test, these commands are subsequently redefined so that PRINT scales and SCALE prints. Main program PIGTST sets up the commands and later redefines them. Subroutines PRINT and SCALE are the two applications procedures.
PIGLET accepts command input from channel 3 (#CR0) in PIGS command syntax (see Section 1.3 of the PIGS manual for a full description). Briefly, commands usually consist of a command name followed by arguments separated from the command name and each other by commas, for example:
SCALE,3.0,4,10
PRINT,5,49
The set of commands available at a given time is determined by the application program.
PIGLET consists of procedures to define, poll for and execute commands plus the PIGS free format command parsing subroutines. Eight-character command names are matched to application procedure entry addresses in a PIGLET internal table. A command set of 127 commands may be defined at any one time using PIGLET procedures. Commands may be redefined or erased as desired.
Three functions must be carried out by an application using PIGLET:
(1) Initialise PIGLET data base
(2) Define or redefine the available command set by matching command names to applications procedures
(3) Poll for a command and execute its related application procedure
Steps (1), (2) and (3) may be repeated as many times as desired. The four procedures below perform these functions and constitute the application program interface to PIGLET.
(1) SUBROUTINE NEWJMP
This procedure should be called before any other PIGLET procedure, otherwise an error message will result. It defines PIGLET constants, erases the current command set and defines permanent command 128, 'RET.' (See (3), below). After initialisation, NEWJP may be used to clear the entire current command set for redefinition.
(2) FUNCTION JMPDEF (CNAM, ISNAM)
EXTERNAL ISNAM
This procedure defines (or redefines) a command name and matching application procedure entry point. CNAME is a 8 character (or shorter) command name. ISNAM, declared EXTERNAL by the calling program, is the name of the application procedure. On return, JMPDEF is the index of the command in the current command set (0-127). If JMPDEF=O, the command was not defined because the command set was full, If CNAM as already defined in the current command set, the previously associated application procedure is replaced by entry point ISNAM.
(3) FUNCTION JMPCOM (LEXEC, IRET)
LOGICAL LEXEC,LRET
JMPCOM sends error diagnostics channel 4 and reads commands from channel 3. If LEXEC is .TRUE. the associated application procedure is subsequently executed by JNPCOM using JUMP (see(4) below). If LEXEC is .FALSE. the applications procedure is not executed. Next, if LRET is .TRUE., control returns to the caller. If LRET is .FALSE., JMPCOM polls for another command until the special command:
RET. <cr>
is read. At this point control returns to the calling routine. On return, the value of JNPCOM will be an integer between 0 and 128:
0 Error 32, no commands defined,
1-127 Index of command selected, This index is also
returned by JMPDEF.
128 Special command RET. was selected.
(4) SUBROUTINE JUMP (ICNDEX)
If subroutine JMPCOM is called with LEXEC and LRET = .FALSE., control will return to the calling routine when a command is selected. The associated command procedure may then be executed, if desired, using subroutine JUMP. Parameter ICNDEX is the index of the selected command (1≤ICNDEX≤127). The calling program should take care that ICNDEX has a value in the proper range (not 0 or 128). Control will return to the calling routine directly from the application procedure.
GETCH
GETDP
GETSI
GETSR
SUBROUTINE ARGUMENTS FILE DESCRIPTION
NAME NAME
GETCH GETCH2 Get character string,
left justified, blank filled.
NOARG Integer index of argument
STRING First element of real array to
hold returned string
NOCHAR Returns number of characters
in string argument
MAXCH Maximum number of characters
before overflow
GETDP GETDP2 Get double precision number
NOARG Integer index of argument
DUBPRE Returns double precision
argument value
GETSI GETSI2 Get single integer number
NOARG Integer index of number
INTEGER Returns double precision
argument value
GETSR GETSR2 Get single real number
NOARG Integer index of argument
REALNO Returns real argument value
Error messages in PIGLET derive from the PIGS system and, therefore, some of the messages listed below are not applicable in PIGLET:
| ERROR NUMBER |
DESCRIPTION | ACTION TAKEN |
PRTE OR MENDEL SOURCE |
|---|---|---|---|
| 901 | Keyboard input buffer overflow. Too many characters typed | Command ignored | KEYIN |
| 902 | Format error in command string | Command ignored | TARGS |
| 903 | Index of argument to be retrieved is .LT. 0 .GT. 14 | Default argument returned | GETDP, GETCH |
| 904 | Number argument to be retrieved, but string argument input | Default argument returned | GETDP |
| 905 | Number argument to be retrieved would overflow integer variable | Default argument returned | GETSI |
| 906 | Command index in Command Table out of range | Command ignored | PIGS |
| 907 | Menu block number out of range | New menu not actuated | PIGS |
| 908 | Command name not recognised | Command ignored | PIGS,PIGLET |
| 909 | String argument to be retrieved, but number argument input | Command ignored | GETCH |
| 910 | Index of argument to be put is .LT. 0 or .GT. 14 | Argument is type omitted | PUTDP,PUTCH |
| 911 | A necessary argument to this command was omitted | Command ignored | YYCRE,YYDSAB,YYEDI,YYMEN,YYMXD,YYSBD |
| 912 | String argument would overflow buffer if retrieved | Default argument returned | GETCH |
| 913 | All menu blocks allocated are full | Command ignored | YYOUT |
| 914 | Reference to an undeclared application procedure name | Command ignored | YYCOM |
| 915 | Reference to an undeclared menu name | Command ignored | YYCOM,YYEND,YYXEN |
| 916 | Unrecognised or illegal argument for this command | Command ignored | YYCOM,YYDSAB,YYKEY,YYSTY |
| 917 | Argument value out of range | Command ignored | YYLOCL,YYPUSH |
| 918 | Menu block full, command not entered | Command ignored | YYCOM |
| 919 | Illegal command for this MENDEL context | Command ignored | YYCERR,YYNCX |
| 920 | Command name not found | Command ignored | YYPOS |
| 921 | Would position cursor off last menu block. Cursor unchanged | Command ignored | YYGTB,YYPOS |
| 922 | Command illegal in MENDEL edit mode | Command ignored | YYBIG |
| 923 | Command illegal in MENDEL create mode | Command ignored | YYNED |
| 924 | End of block reached by DEL command, cursor unchanged | Command ignored | YYDEL |
| 925 | File not found | MENDEL - Retype option string, PRTE - Ignore read request | |
| 926 | File read error | MENDEL - Abort assembly or edit, PRTE - Ignore read request | |
| 927 | Unexpected EOF on input file | MENDEL - Abort assembly or edit, PRTE - Ignore read request | |
| 928 | File write error | MENDEL - Abort assembly or edit, PRTE - Ignore write request | YYOUT,WTMNU |
| 929 | MNB file size error | Ignore file request | OPMNB |
| 930 | Clock schedule full or time interval too large | Command not scheduled | SCHDEL |
| 931 | Command set full | Command not defined | PIGLET (JMPDEF) |
| 932 | POLLING requested, no commands defined | Return to caller | PIGLET (JMPCOM) |
The PIGLET subroutines exist as a NULLIB library :GSIN08.PIGLIB and is trapped to all users for READ and EXECUTE access. A list of all the FORTRAN and PLASYD subroutine names is given below:
ABORT GETSI NEWJMP PUTCH ADPUTP GETSR NXTCHR PUTDP BLANKS JMPCOM PARG PUTSI DUMPARG JPDEF PINT PUTSR ERRMES JUMP PMORTM TARGS GETCH JUMPP PNUMB TERMIN GETDP MVC PSTRING YYCARG
Channel Use
3 Command input
4 Error messages
MASTER PIGTST
C
C TEST PIGLET CN ICL 1906A AXO DEMONSRATE ITS USE
C
C HAVING SET UP AN ARRAY OF NUMBERS, USE PIGLET TO PRINT OUT A
C SELECTEO SECTION OR MULTIPLY A SECTION OF THAT ARRAY BY A CONSTANT
C
LOGICAL LEXEC,LRET
C
C APPLICATION PROCEDURES MUST 8E OECLAREO EXTERNAL
C
EXTERNAL PRINT,SCALE
COMMON /ARRAY/ RARR(50)
C
C INITIALISE ARRAY FOR TEST
C
DO 10 I=1,50
RARR(I)=I
10 CONTINUE
C
C TEST 1
C
C INITIALISE PIGLET, CLEAR COMMAND SET
C
WRITE (4,1012)
1012 FORMAT (//1X,' TEST 1',/)
CALL NEWJMP
C
C DEFINE COMMANDS IN THIS SET
C
CALL JMPDEF (8HPRINT ,PRINT)
CALL JMPDEF (8HSCALE ,SCALE)
C
C POLL UNTIL CCMMAND SELECTED, EXECUTE THEN RETURN
C EXIT FROM TEST USING RET, COMMANO
C
LEXEC=.TRUE.
LRET=.FALSE.
I=JMPC0M (LEXEC,LRET)
C
C
C TEST 2
C
C REDEFINE SCALE COMMAND ONLY, POLL, AND RETURN INDEX WITHOUT EXECUTING
C COMMAND, WRITE COMMAND INDEX ON CHANNEL 4
C
WRITE (4,1018)
1018 FORMAT(//1X,' TEST 2',/ )
CALL JMPDEF (8HSCALE ,PRINT)
20 I=JMPCOM (.FALSE.,.TRUE.)
WRITE (4,1020) I
1020 FORMAT (1X,'COMMAND INOEX=',I6)
C
C RET, COMMAND INDEX IS 128
C
IF (I.NE.128) GOTO 20
C
C
C TEST 3
C
C REDEFINE ENTIRE CCMMAND SET, EXECUTE COMMANDS FROM USER PROGRAM.
C
WRITE (4,1028)
1028 FORMAT (//1X,' TEST 3',/)
CALL NEWJMP
CALL JMPDEF (8HSCALE ,PRINT)
CALL JMPDEF (8HPRINT ,SCALE)
C
C I IS INDEX OF COMMAND SELECTEO
C
30 I=JMPCOM (.FALSE.,.TRUE.)
C
C DON'T ALLOW JUMP(I) WHERE I IS OUT OF RANGE
C
IF (I.LE.0).OR.(I.GE.128)) GOTO 40
CALL JUMP (I)
C
C END OF .RET COMMAND
C
IF (I.EQ.128) GOTO 40
GOTO 30
C
C END OF TEST SEQUENCE
C
40 WRITE (4,1040)
1040 FORMNAT (/1X,'END OF PIGLET TEST SEQUENCE')
C
STOP
END
PRINT,1,10
SCALE ,3,4,20,30
PRINT, 25,20
PRINT,20,20
RET,
PRINT ,30,40
'SCALE',-10,20
SCALE,30,40
RET,
PRINT, 0,1 , 40 , 50
SCALE,40,45
PRINT,10,45,50
SCALE,1,50
RET.
TEST 1
1.0000 2.0000 3.0000 4.0000
6.0000 7.0000 8.0000 9.0000
PRINT ARGUMENTS INCORRECT= 25 20
68.0000
TEST 2
COMMAND INDEX- 1
COMMAND INDEX- 2
COMMAND INDEX- 2
COMMAND INDEX- 128
TEST 3
4.0000 4.1000 4.2000 4.3000 4.4000
4.5000
1.0000 2.0000 3.0000 4.0000 5.0000
6.0000 7.0000 8.0000 9.0000 10.0000
11.0000 12.0000 13.0000 14.0000 15.0000
16.0000 17.0000 18.0000 19.0000 68.0000
71.4000 74.8000 78.2000 81.6000 85.0000
88.4000 91.8000 95.2000 98.6000 102.0000
31.0000 32.0000 33.0000 34.0000 35.0000
36.0000 37.0000 38.0000 39.0000 4.0000
4.1000 4.2000 4.3000 4.4000 45.0000
46.0000 47.0000 48.0000 49.0000 50.0000
END OF PIGLET TEST SEQUENCES