GIDIS consists of four FORTRAN system subroutines that can be used on the Professional Series only, instead of using the .SPFUN programmed requests:
GICLOS GIOPEN GIREAD GIWRIT
Each GIDIS subroutine can return error information in a 2-word status array.
Relevant error codes are listed with each subroutine. See GIDIS error codes description and sample GIDIS program.
GICLOS
The GICLOS subroutine ends the GIDIS connection to the Professional interface (PI) handler. The output device treats a GICLOS subroutine as an END-PICTURE instruction. Control is returned to the calling program once all data specified by the GIWRIT subroutine has been sent to the output device.
Form:
GICLOS (status,lun) where:
status is a 2-word integer array used to return a code indicating the results of the requested operation
lun is the unit number assigned by GIOPEN to terminate. If no GIOPEN has been sent for the specified value, statusis set to (-5,-1)
Errors:
See GIDIS error codes.
Example:
See sample GIDIS program.
GIOPEN
The GIOPEN subroutine initiates contact with the Professional interface (PI) handler and assigns a logical unit number (LUN) for this GIDIS operation. GIOPEN does not affect the current GIDIS state; all attributes currently selected remain in force.
To initialize the Professional video screen, execute the INITIALIZE -1 (complete initialization) instruction followed by the NEW_PICTURE instruction.
Form:
GIOPEN (status,lun[,message][,msglen][,devtype][,driver])
System Subroutine Description and Examples 2–57
GICLOS/GIOPEN/GIREAD/GIWRIT (GIDIS)
where:
status is a 2-word integer array to return a code indicating the results of the requested operation
lun is the unit number to associate with this GIOPEN; an integer number from 0 through 15
Iflunis already connected to a GIDIS operation,statusis set to (-5,-4) message is a word containing a 0
msglen is the number of words in the message; normally a 1. If msglen is less than 0 or greater than 128(decimal) words,statusis set to (-5,-3) devtype is 6. Integer values 0 through 5, 7, and 8 are reserved
driver is 0
The GIREAD subroutine returns a report from GIDIS requested by a report handling instruction sent by GIWRIT. GIREAD waits until GIDIS returns a report, then places the report in the buffer. If the report is longer than the buffer, the excess is lost.
If the report is shorter than the buffer, the trailing words of the buffer are left unchanged. The first byte of the report contains the number of data words in the report.
Form:
GIREAD (status,lun,buffer,buflen) where:
status is a 2-word integer array used to return a code indicating the results of the requested operation
lun is the unit number assigned by GIOPEN. If no GIOPEN has been issued for the specified value,statusis set to (-5,-1)
buffer is the buffer for the report returned by GIDIS buflen is the number of words in the report buffer Errors:
See GIDIS error codes.
Example:
See sample GIDIS program.
GIWRIT
The GIWRIT subroutine sends the buffer of GIDIS command data to the Professional interface (PI) handler. You can pass a maximum of 2048(decimal) words to PI in one
2–58 RT–11 System Subroutine Library Manual
GICLOS/GIOPEN/GIREAD/GIWRIT (GIDIS) GIWRIT system subroutine. The data in the buffer need not start or end on a command boundary.
Form:
GIWRIT (status,lun,message,msglen) where:
status is a 2-word integer array used to return a code indicating the results of the requested operation
lun is the unit number assigned by GIOPEN. If no GIOPEN has been executed for the specified value, status is set to (-5,-1)
message is the command data to send
msglen is the number of words in the message.
Themsglen parameter accepts a value equal to or greater than -1. Specify the -1 value formsglen to reset GIDIS. If less than 0 or greater than 2048(decimal) words, status is set to (-5,-3)
Errors:
See GIDIS error codes.
Example:
See sample GIDIS program.
GIDIS Error Codes
GIDIS subroutines can return the following error codes and subcodes in the 2-word status array. The error code specifies the class of error and is returned in the first word of the status array. The subcode specifies the actual error and is returned in the second word of the status array.
Directive error code (-1) can return the following subcode:
-1 No handler. The output device handler is not loaded.
Interface error code (-5) can return the following subcodes:
-1 Channel not open. The logical unit number (LUN) for that GIDIS is not assigned.
-2 DEVTYPE is out of range or invalid. The output device specified in a GIOPEN is invalid.
-3 MSGLEN out of range. The message length in a GIOPEN or GIWRIT is out of range.
-4 Channel in use. The logical unit number (LUN) specified for that GIDIS is already in use.
System Subroutine Description and Examples 2–59
GICLOS/GIOPEN/GIREAD/GIWRIT (GIDIS)
RT–11 specific error code (-7) can return the following subcodes during a GIDIS operation:
-1 Required argument missing. A required argument in a GIDIS subroutine is not specified.
-2 Handler not loaded. The output device handler is not loaded.
-3 File not found. The indicated file was not found on the device.
-4 File open on nonshareable or non-file-structured device.
-5 An attempt was made to read or write past the end-of-file (EOF) mark.
-6 Hard error. The GIDIS operation experienced a hard error on the output device.
Errors that occur if .SERR is in effect are listed under the .SERR request in the RT–11 System Macro Library Manual.
2–60 RT–11 System Subroutine Library Manual
GICLOS/GIOPEN/GIREAD/GIWRIT (GIDIS)
Sample GIDIS Program
The following FORTRAN program fragment uses the GIDIS subroutines to request the current cursor position:
Program FGIDCA !demo GIDIS interface routines C
C Declare storage C
Integer*2 BUFLEN, LUN, MSGLEN, OCLEN, OPCODE Integer*2 BUFFER(3), MESSAG(1), STATUS(2) C
C user program here C
LUN = 5 !assign logical unit number OPCODE = 55*256 !request current position OCLEN = 0 !opcode length is 0
C
C Put OPCODE and OCLEN into MESSAG buffer C
MESSAG(1) = OPCODE + OCLEN
MSGLEN = 1 !length of message C
C Send to GIDIS C
Call GIWRIT (STATUS, LUN, MESSAG, MSGLEN) If (STATUS(1) .le. 0) Go To 999 ! error C
BUFLEN = 3 !length of report C
C Get report from GIDIS C
Call GIREAD (STATUS, LUN, BUFFER, BUFLEN) If (STATUS(1) .le. 0) Go To 999 ! error C
C Contents of buffer after successful return:
C
C BUFFER(1) = 258 ((1*256) + 2)
C 1 = report header
C 2 = number of data elements in buffer C BUFFER(2) = Current ’X’ position
C BUFFER(3) = Current ’Y’ position C
C more user program C
999 Continue !diagnose errors here
End
System Subroutine Description and Examples 2–61