| Integrated Preprocessor Interface |
This chapter describes the set of COBOL system library routines that can help you control the environment your application is running in.
Object COBOL provides routines in the following categories:
| CBL_SUBSYSTEM | Declare/deallocate subsystems |
The application subsystem routine enables you to logically group a number of programs. This enables you to cancel these programs, the subsystem, with a single statement.
| CBL_ERROR_PROC | Register error procedures |
| CBL_EXIT_PROC | Register closedown procedure |
CBL_ERROR_PROC is not available with the 16-bit static-linked run-time system.
The exit and error procedure routines enable you to register your own E:\iview\iview32.exeroutines which are executed by the run-time system when your application terminates, either normally or abnormally.
| CBL_GET_OS_INFO | Get operating system information |
| CBL_SCR_SET_PC_ATTRIBUTES | Set up IBM-PC attribute palette |
These routines are provided to help you make existing applications portable to other environments. They should not be used in new applications where alternative mechanisms are provided.
| PC_PRINT_FILE | Print a file |
| PC_PRINTER_CLOSE | Close a printer channel |
| PC_PRINTER_CONTROL | Send a printer command to a printer |
| PC_PRINTER_FREE_BMP | Free bitmap from memory |
| PC_PRINTER_INFO | Get printer information |
| PC_PRINTER_LOAD_BMP | Load bitmap into memory |
| PC_PRINTER_OPEN | Open a printer channel |
| PC_PRINTER_SET_COLOR | Set printer color |
| PC_PRINTER_SET_FONT | Set printer font |
| PC_PRINTER_WRITE | Write text to a printer |
| PC_PRINTER_WRITE_BMP | Write bitmap to a printer |
| PC_TEST_PRINTER | Test printer status |
The PC_PRINTER_ routines are available on 32-bit systems only.
The routine PC_TEST_PRINTER is available only in DOS environments.
| CBL_TOLOWER | Convert a string to lower case |
| CBL_TOUPPER | Convert a string to upper case |
| CBL_CLOSE_VFILE | Close heap |
| CBL_OPEN_VFILE | Open heap |
| CBL_READ_VFILE | Read from heap |
| CBL_WRITE_VFILE | Write to heap |
A heap is a byte-stream file which is buffered in available memory.
The status word specified when the heap is created is associated with each heap. It is written to when an operation on the heap fails. Each heap is thereby attached to a particular program, namely the program which contains the heap's status word, and is automatically deallocated (unless it has already been explicitly deallocated by a call to CBL_CLOSE_VFILE) when that program is canceled.
A heap is identified by a heap identifier word. This can be passed around between programs so that the heap can be read or written by any program. However, in order to check for failure, the program needs to have access (using a pointer variable, for example, or via normal linkage section mapping) to the associated status word.
Alternatively the RETURN-CODE register can be examined to catch a general heap function failure, or the ON OVERFLOW/EXCEPTION syntax can also be used on the CALL statement to trap any error. In these two cases, the specific error can then be determined by examining the heap status word.
If the read/write succeeds, the RETURN-CODE is zero. If it fails, the RETURN-CODE is nonzero and the heap status first byte contains "9", with detail in the second byte.
On 16-bit environments the heap status word used by CBL_READ_VFILE and CBL_WRITE_VFILE, must reside in the first 64K of a COBOL program: it can be in the Linkage Section of the current program, as long as it is in the first 64K of another COBOL program.
The buffer used with CBL_READ_VFILE and CBL_WRITE_VFILE can reside anywhere in the Data or Linkage Section, or it can be dynamically allocated using the CBL_ALLOC_MEM routine. On 16-bit environments, the buffer must not cross a 64K boundary. Use the FLAG-CHIP directive to highlight data items that cross a 64K boundary.
Each heap is paged, if necessary. On DOS, Windows and OS/2, a heap is paged into a separate file on disk with name sourcename.Vnn, where sourcename is the base-name of the program to which the heap is attached and nn is an integer from 1 to 99. Once nn reaches 99, the V is overwritten. The maximum number allowed for the extension is 384.
With the 16-bit COBOL system, each program is limited to 384 local heaps. On UNIX each run-unit is limited to 128 local heaps. With the 32-bit COBOL system for Windows NT and OS/2 V2, the number of local heaps is configurable, up to 65535.
You can use reference modification in the buffer call parameter to declare the heap buffer in the middle of a COBOL record. This is compiled efficiently provided the length is given as fixed; since the length is ignored by the call interface, you can give it as one.
| X"84" | Execute a DOS Interrupt |
| X"85" | Read a Byte from Memory |
| X"86" | Write to a Byte in Memory |
| X"87" | Read Byte from Hardware Port |
| X"88" | Write Byte to Hardware Port |
| X"91" function 11 | Set Programmable Switches |
| X"91" function 12 | Read Programmable Switches |
| X"91" function 13 | Set Run-time Switches |
| X"91" function 14 | Read Run-time Switches |
| X"91" function 15 | Check Program Exists |
| X"91" function 16 | Count Linkage Parameters |
| X"91" function 35 | Execute a Program |
| X"91" function 60 | Fix Data in Memory |
| X"91" function 61 | Unfix Data in Memory |
| X"94" | Read a Word from Memory |
| X"95" | Write to Word in Memory |
| X"96" | Read Word from Hardware Port |
| X"97" | Write Word to Hardware Port |
Descriptions for all of the call-by-name routines appear alphabetically. Each description contains the routine name and function followed by these sections (as appropriate):
| Syntax: | Shows the CALL statement you could
use to call the routine.
The optional RETURNING clause is also shown. Every routine returns a value showing the result of the operation. Unless otherwise indicated, zero indicates success, nonzero indicates failure. This value is left in the data item specified in the RETURNING clause, in this reference, status-code. If this clause is omitted, the value is left in the special register RETURN-CODE. (If call-convention bit two is set, RETURN-CODE is not changed.) status-code must be a numeric data item capable of holding positive values from 0 to 65535; for example, PIC X(2) COMP-5. The name of the routine must be coded in upper case. |
| Parameters: |
Describes any parameters shown in the RETURNING and USING clause. A parameter enclosed in brackets, for example, [parameter1] is optional and might not be needed for all forms of the routine. |
| On Entry: | Indicates which of the parameters shown are passed on entry |
| On Exit: | Indicates which of the parameters
shown are returned on exit.
Where bits of one or more bytes are referenced, bit 0 is the least significant (rightmost) bit. |
| Comments: | Provides any additional information necessary for the successful use of the routine |
| See also: | Lists other related topics. |
The routines are listed in alphabetical order.
Closes a heap.
call "CBL_CLOSE_VFILE" using by value heap-id
returning status-code
heap-id |
pic x(2) comp-5. |
status-code |
See Key |
heap-id |
This contains the heap handle assigned when the heap was opened. |
None
Introduction to Virtual Heap Routines
Installs or removes an error procedure to be invoked automatically when a run-time system error occurs.
call "CBL_ERROR_PROC" using install-flag
install-addrs
returning status-code
install-flag |
pic x comp-x. |
install-addrs |
usage procedure-pointer. |
status-code |
See Key |
install-flag |
The operation to be performed:
|
||||
install-addrs |
Address of error procedure to install or de-install. |
None
This routine is not supported on the16-bit static-linked run-time system. If a program that contains a call to this routine has been linked using the16-bit static-linked run-time system, then any attempt to link or run the program will result in an error.
You can install several error procedures for an application by repeatedly calling this routine.
Once an error procedure has been posted, subsequent attempts to install that error procedure are silently ignored until it is removed either implicitly (for example, during error processing) or explicitly (by calling CBL_ERROR_PROC with install-flag set to "1").
An error procedure can be written in any language. If it is in COBOL, install-addrs must be the address of an entry point. You can obtain this address using the statement:
set install-addrs to entry entry-name
An error procedure in COBOL can include any legal COBOL, including CALL statements.
When an error occurs the installed procedures are executed, starting with the most recently installed and ending with the first one installed. When all have been processed, the run-time system error handling procedure is then started.
If you don't want any other error procedures, including the run-time system error handling, to be executed after terminating your error procedure, set RETURN-CODE to zero.
If a program containing an error procedure is canceled, the error procedure is removed.
An error procedure installed in one program can be removed by another program.
On 32-bit systems, an error procedure can install an error procedure. On the 16-bit system, it cannot.
If an error procedure is installed during error processing (either by itself, or by another error procedure) then it is executed as soon as the error procedure that installed it returns, assuming that it doesn't return with a ZERO return code.
If a run-time system error occurs in an error procedure, the procedure is terminated. The run-time system then processes the new run-time system error, starting with the next error procedure, if there is one.
You must ensure that the procedure-pointer you use to install the procedure is valid.
An error procedure belongs to the run-unit from which it was installed. So the error procedure is executed only by the run-unit that installed it.
Pressing interrupt does not cause any error procedures to be called.
If the error procedure is defined as an entry point in a program that itself could give an error, you must to ensure that the program has a Local-Storage Section. This ensures that the program is reentrant and the run-time system will not give error 166 ("Recursive COBOL call is illegal") when trying to execute the error procedure.
When an installed error procedure is called, the character string containing the relevant run-time system error message is passed as a parameter. The format of the parameter differs between 32-bit systems and the 16-bit system.
On 32-bit systems you should define this parameter in the Linkage Section as PIC X(325), and include it in the USING phrase of the entry to the error procedure. An example of the run-time system error message string follows:
Load Error : file 'prog-name'\n error code: 173, pc=0, call=-1, seg=0\n 173 Called program file not found in drive/directory\n\0
where \n is a new-line character and \0 is a null (x"00") terminator. This format is described in your Error Messages.
On 16-bit systems the format of the parameter passed to the error procedure is as follows:
error-type0error-num0prog-name0seg-no0pc0 error-text0file-name00
where the parameters are:
error-type |
The error type, as follows:
|
||||||
error-num |
The actual error number | ||||||
prog-name |
The program in which the error occured | ||||||
seg-no |
The segment number in which the error occurred (RT = Root) | ||||||
pc |
The COBOL PC at which the error occured | ||||||
error-text |
The error description text | ||||||
filename |
Depends on the error-type, as follows:
|
||||||
0 |
A null character - x"00". |
The following is an example of installing an error procedure, and the skeleton of the error procedure that is called if an error occurs.
working-storage section
01 install-flag pic x comp-x value 0.
01 install-address usage procedure-pointer.
01 status-code pic 9(4) comp value zeros.
linkage section.
01 err-msg pic x(325).
procedure division.
set install-address to entry "err-proc".
call "CBL_ERROR_PROC" using install-flag
install-address
returning status-code.
* Error procedure:
entry "err-proc" using err-msg.
* Process err-msg to find out the error number.
* Act accordingly.
...
* Terminate, but allow other error procedures to be executed.
move 1 to return-code
exit program
stop run.
The following are examples of the information passed to the error procedure. In these examples, the spaces between numbers are included for clarity and do not actually appear in the parameter:
A run-time system error 163 in program ERRORP.GNT in the Root segment at COBOL PC 033D gives:
0 0 163 0 ERRORP.GNT 0 RT 0 033D 0
Illegal character in numeric field (Error 163) 00
A run-time system error 013 in program APE.INT in the Root segment at COBOL PC 0080 on file xyz gives:
1 0 013 0 APE.INT 0 RT 0 0080 0
File not found (Error 013) 0 xyz 00
A run-time system error 173 in program APE.INT in the Root segment at COBOL PC 0053 on program PROG1 gives:
2 0 173 0 APE.INT 0 RT 0 0053 0
Called program file not found in drive/directory (Error 173) 0 PROG1 00
Example Error Procedure for CBL_ERROR_PROC
Installs or removes a closedown procedure to be invoked automatically when the application terminates.
call "CBL_EXIT_PROC" using install-flag
install-params
returning status-code
install-flag |
pic x comp-x. |
install-params |
Group item defined as: |
install-addrs |
usage procedure-pointer |
install-prrty |
pic x comp-x |
status-code |
See Key |
install-flag |
The operation to be performed:
|
||||||||
install-addrs |
Address of closedown procedure to install, de-install or query. | ||||||||
install-prrty |
When install-flag is 3, contains the
priority of the closedown procedure being installed, in range 0 to 127.
Otherwise, ignored. |
install-prrty |
When install-flag is set to 2, returns
the priority of the selected procedure. |
The installed closedown procedure is executed whether the application finishes normally (with a STOP RUN) or abnormally (for example, with a keyboard interrupt or run-time system error). You can install several closedown procedures for an application by repeated calls of this routine.
A closedown procedure can be written in any language. If it is in COBOL, install-addrs must be the address of an entry point. You can obtain this address using the statement:
set install-addrs to entry "entry-name"
A closedown procedure in COBOL can include any legal COBOL, including call statements. The closedown procedure terminates when the main program in the procedure executes an EXIT PROGRAM/GOBACK or when a STOP RUN statement is executed.
A closedown procedure does not have any parameters passed to it when it is called.
With the 16-bit COBOL system, a closedown procedure in any other language must preserve the i86 machine code BP register and direction flag, and terminate with a far return (RETF) instruction; that is, it must be a far procedure.
Every closedown procedure installed has a priority. This priority determines the order in which the procedures are executed - procedures with the lowest values are processed first. If several procedures have the same priority, they are executed in reverse order of installation - that is the last one installed is executed first.
Procedures installed without a priority (install-flag = 0) are given the default priority of 64. To set your own priority, set install-flag = 3 and set the priority to a value in the range 0 to 127. Priorities 128 to 256 are reserved for use by the COBOL system. You must not set a priority higher than 127 unless your program is a user-written file handler, in which case it must be 200.
If a closedown procedure has already been installed, an attempt to install again fails. However, if the priority used on the second attempt is different to that used when it was installed, its priority is changed. RETURN-CODE is set to zero.
Use install-flag = 2 to find the priority of a previously installed procedure. This returns the priority in install-prrty if it is found The procedure is identified by its install-addrs. If the procedure cannot be found, RETURN-CODE is set nonzero.
Returns information about the operating system environment.
call "CBL_GET_OS_INFO" using parameter-block
returning status-code
parameter-block |
Group item defined as: |
parameter-size |
pic x(2) comp-x value 14 |
p-os-type |
pic x comp-x. |
p-os-version |
pic x(4) comp-x. |
p-DBCS-support |
pic x comp-x. |
p-char-coding |
pic x comp-x. |
p-country-id |
pic x(2) comp-x. |
p-code-page |
pic x(2) comp-x. |
p-process-type |
pic x comp-x. |
status-code |
See Key |
p-os-type |
COBOL system (16- or 32-bit) and Operating System:
|
||||||||||||||||||
p-os-version |
Use is specific to the operating system. Can include information such as chip type and the operating system version number. For DOS, Windows and OS/2, the third and fourth bytes contain the minor and major release operating system version number respectively. | ||||||||||||||||||
p-DBCS-support |
DBCS support flag:
|
||||||||||||||||||
p-char-coding |
Character encoding:
|
||||||||||||||||||
p-country-id |
Country code. See your operating system documentation for an
explanation of country codes.
Not supported in UNIX environments, set to zero. |
||||||||||||||||||
p-code-page |
Code page. See your operating system documentation for an
explanation of code page codes.
Not supported in UNIX environments, set to zero. |
||||||||||||||||||
p-process-type |
Process type:
Not supported in UNIX environments - undefined. |
Opens a heap.
call "CBL_OPEN_VFILE" using heap-id
status-word
returning status-code
heap-id |
pic x(2) comp-5. |
status-word |
pic x(2). |
200status-code |
See Key |
None
heap-id |
Contains the assigned heap handle. A heap handle of zero means the open failed. | ||||||||||||
status-word |
The status word for the heap, set to zero on the open. When
the first status byte contains the character 9, binary values in the second
status byte are:
If a program in which a heap status word actually exists (that is, it is not in a Linkage Section) is canceled, all heaps with status words in that program are automatically canceled, and the heap identifiers (which might have been passed to other programs) should not be used any more. |
Introduction to Virtual Heap Routines
Reads bytes from a heap.
call "CBL_READ_VFILE" using by value heap-id
heap-ref
heap-length
by reference heap-buffer
returning status-code
heap-id |
pic x(2) comp-5. |
heap-ref |
pic x(4) comp-5. |
heap-length |
pic x(4) comp-5. |
heap-buffer |
pic x(n). |
status-code |
See Key |
heap-id |
This contains the heap handle assigned when the heap was opened. |
heap-ref |
Offset in the heap at which to start reading. |
heap-length |
Number of bytes to read. |
heap-buffer |
Buffer into which bytes are read. It is your program's responsibility to ensure that the buffer is large enough to hold the number of bytes being read. |
Trying to read data from an area of the heap which has not yet been written results in indeterminate data being returned to the buffer.
Introduction to Virtual Heap Routines
Sets up the current COBOL attribute table so as to emulate, as closely as possible, the IBM-PC attribute table.
call "CBL_SCR_SET_PC_ATTRIBUTES" returning status-code
status-code |
See Key |
None
status-code |
The return status:
|
Using this routine is equivalent to setting the entire IBM-PC attribute table using the generic attribute routines. It is provided to enable you to apply generic attributes to existing programs, making their attribute handling portable. However, this routine is inefficient because it defines every possible attribute. For new applications use the generic attribute routines and define only the attributes you need.
See Introduction to Display Attribute Routines for important information about using this routine.
Declares or deallocates subsystems.
call "CBL_SUBSYSTEM" using function-code
parameter
returning status-code
function-code |
pic x comp-x. Contains one of the following values:
|
||||||
| With function-code = 0 | |||||||
parameter |
Group item defined as: | ||||||
ss-handle |
pic x(2) comp-x. | ||||||
ss-name-len |
pic x(2) comp-x. | ||||||
ss-name |
pic x(n) | ||||||
| With function-code = 1: | |||||||
parameter |
pic x(2) comp-x. | ||||||
| With function-code = 2: | |||||||
parameter |
pic x(2) comp-x value 0 | ||||||
status-code |
See Key |
function-code |
The subfunction value. |
| With function-code = 0 | |
ss-name-len |
The length of subsystem program-name field. |
ss-name |
The subsystem program-name (space-terminated). This must be a COBOL .int file or .gnt file. |
| With function-code = 1: | |
ss-handle |
The subsystem handle returned by a function 0 call. |
| With function-code = 2: | |
| dummy-param | Value 0. |
With function-code = 0:
ss-handle |
The subsystem handle. |
This routine is not available when using the static linked run-time system (16-bit COBOL system) under DOS, Windows and OS/2. Any program containing this routine links correctly, but the call has no effect.
A subsystem is defined to be a specified program in an application, plus any subprograms subsequently called by programs already in the subsystem that do not already belong to any other subsystems.
| With function-code = 0: |
This function declares a subsystem. The routine returns a subsystem handle. If the program is not already loaded the function loads it. If an error occurs in finding or loading the program a subsystem handle of zero is returned. A program belonging to a subsystem is only deallocated (that is, deleted from memory), when either it is canceled by the CANCEL verb, or the program cancels the entire subsystem using function-code = 1, or the application executes a STOP RUN or CHAIN statement. The main program of a subsystem should not be canceled with the CANCEL statement unless all other programs in the subsystem have already been canceled. |
| With function-code = 1: |
This function cancels all programs in the specified subsystem. If any program in the subsystem is still active, that program is released from the subsystem and is not canceled. |
| With function-code = 2: |
This function removes the program that called it from any subsystem the program is in. To ensure a program is never included in any subsystem, call this function at the start of each entry in to the program. |
Converts a string of letters to lower case.
call "CBL_TOLOWER" using string
by value length
returning status-code
string |
pic x(n). |
length |
pic x(4) comp-5. |
status-code |
See Key |
string |
The string to convert. |
length |
The number of bytes of string to change; positions beyond this are unchanged. |
string |
The converted string. |
The routine starts at the left-hand end of string and converts letters to lower case (also called folding to lower case).
Converts a string of letters to upper case.
call "CBL_TOUPPER" using string
by value length
returning status-code
string |
pic x(n). |
length |
pic x(4) comp-5. |
status-code |
See Key |
string |
The string to convert. |
length |
The number of bytes of string to change; positions beyond this are unchanged. |
string |
The converted string. |
The routine starts at the left-hand end of string and converts letters to upper case (also called folding to upper case).
Writes bytes to a heap.
call "CBL_WRITE_VFILE" using by value heap-id
heap-ref
heap-length
by reference heap-buffer
returning status-code
heap-id |
pic x(2) comp-5. |
heap-ref |
pic x(4) comp-5. |
heap-length |
pic x(4) comp-5. |
heap-buffer |
pic x(n). |
status-code |
See Key |
heap-id |
This contains the heap handle assigned when the heap was opened. |
heap-ref |
Offset in the heap at which to start writing. |
heap-length |
Number of bytes to write. |
heap-buffer |
Buffer from which bytes are written. It is your program's responsibility to ensure that the buffer is large enough to hold the number of bytes being written. |
None
Introduction to Virtual Heap Routines
Sends the specified file to the printer.
call "PC_PRINT_FILE" using filename
document-title
by value flags
by value window-handle
returning status-code
filename |
pic x(n). | |
document-title |
Group item defined as: | |
title-len |
pic x(2) comp-5. | |
title-text |
pic x(n). | |
flags |
Numeric literal or pic x(4) comp-5. | |
window-handle |
Numeric literal or pic x(4) comp-5. | |
status-code |
See Key | |
filename |
The name of the file to be printed. The name must be space- or null-terminated. | ||||||||||
title-len |
The length of the document title | ||||||||||
title-text |
The title of the document to be printed | ||||||||||
flags |
A set of bits to define printer options:
All remaining bits are reserved for future use and should not be set |
||||||||||
window-handle |
Handle of the parent window. The parent window is used as a reference for positioning dialog boxes on the screen. If window-handle is 0 positioning is system dependent. |
None.
This routine is available in 32-bit environments only.
You can check the success of the call by examining RETURN-CODE.
Closes a previously opened printer channel.
call "PC_PRINTER_CLOSE" using printer-handle
returning status-code
printer-handle |
pic x(4) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. |
None
This routine is available in 32-bit environments only.
You can check the success of the call by examining RETURN-CODE.
Sends a print command to a printer.
call "PC_PRINTER_CONTROL" using printer-handle
by value print-command
returning status-code
printer-handle |
pic x(4) comp-5. |
print-command |
Numeric literal or pic x(4) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. | ||||||
print-command |
The command to send to the printer:
|
None
This routine is available in 32-bit environments only.
You can check the success of the call by examining RETURN-CODE.
Frees a bitmap from memory, releasing its image and palette back to the operating system.
call "PC_PRINTER_FREE_BMP" using printer-handle
by value bmp-id
returning status-code
printer-handle |
pic x(4) comp-5. |
bmp-id |
pic x(4) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. |
bmp-id |
The unique id of the loaded bitmap, returned when the bitmap was loaded. |
status-code |
Printer status code:
|
|||||||
call "PC_PRINTER_FREE_BMP" using printer-handle,
by value bmp-idlogo,
returning printer-retcode
end-call
This routine is available in 32-bit environments only.
PC_PRINTER_LOAD_BMP
PC_PRINTER_WRITE_BMP
Returns a native HDC, HPS, and other information that can be used to enhance the printing of a document by calling native graphics functions directly.
call "PC_PRINTER_INFO" using printer-handle
printer-info-struct
returning status-code
printer-handle |
pic x(4) comp-5. |
printer-info-struct |
Group item containing: |
pi-struct-size |
pic x(4) comp-5. |
printer-hdc |
pic x(4) comp-5. |
printer-hps |
pic x(4) comp-5. |
printer-orient |
pic x(4) comp-5. |
printer-rows |
pic x(4) comp-5. |
printer-cols |
pic x(4) comp-5. |
printer-rows-left |
pic x(4) comp-5. |
printer-max-horz |
pic x(4) comp-5. |
printer-max-vert |
pic x(4) comp-5. |
printer-min-horz |
pic x(4) comp-5. |
printer-min-vert |
pic x(4) comp-5. |
printer-cur-horz |
pic x(4) comp-5. |
printer-cur-vert |
pic x(4) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. |
pi-struct-size |
The size of the structure. |
printer-hdc |
Device context associated with printer-hps | ||||
printer-hps |
Graphic presentation space associated with printer-handle | ||||
printer-orient |
Orientation of the printed output:
|
||||
printer-rows |
Total number of rows on a page, in the current font | ||||
printer-cols |
Total number of columns on a page, in the current font | ||||
printer-rows-left |
Number of rows left on the current page, in the current font | ||||
printer-max-horz |
Maximum value of graphics coordinate available in the horizontal axis | ||||
printer-max-vert |
Maximum value of graphics coordinate available in the vertical axis | ||||
printer-min-horz |
Minimum value of graphics coordinate available in the horizontal axis | ||||
printer-min-vert |
Minimum value of graphics coordinate available in the vertical axis | ||||
printer-cur-horz |
Current graphics X coordinate | ||||
printer-cur-vert |
Current graphics Y coordinate |
This routine is available in 32-bit environments only.
You can check the success of the call by examining RETURN-CODE.
Loads a bitmap into memory ready for the PC_PRINTER_WRITE_BMP function.
call "PC_PRINTER_LOAD_BMP" using printer-handle
by reference bmpfilename
by reference bmp-id
returning status-code
printer-handle |
pic x(4) comp-5. |
bmpfilename |
pic x(n). |
bmp-id |
pic x(4) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. |
bmpfilename |
The name of the file to be printed (null or space terminated). |
bmp-id |
A unique identifier for the loaded bitmap. | ||||||||
status-code |
Printer status code:
|
call "PC_PRINTER_LOAD_BMP" using printer-handle
by reference "mflogo.bmp" & x"0"
by reference bmp-id
returning printer-retcode
end-call
This routine is available in 32-bit environments only.
PC_PRINTER_FREE_BMP
PC_PRINTER_WRITE_BMP
Opens a printer channel, giving it a document title, and optionally displaying the dialog boxes for printer control, font selection, and progress indication.
call "PC_PRINTER_OPEN" using printer-handle
document-title
by value flags
by value window-handle
returning status-code
printer-handle |
pic x(4) comp-5. |
document-title |
Group item defined as: |
title-len |
pic x(2) comp-5. |
title-text |
pic x. |
flags |
Numeric literal or pic x(4) comp-5. |
window-handle |
Numeric literal or pic x(4) comp-5 |
status-code |
See Key |
title-len |
The length of the document title. | ||||||||||
title-text |
The title of the document to be printed. | ||||||||||
flags |
A set of bits to define printer options:
All remaining bits are reserved for future use and should not be set. |
||||||||||
window-handle |
Handle of the parent window. The parent window is used as a reference for positioning dialog boxes on the screen. If window-handle is 0 positioning is system dependent. |
printer-handle |
Returns a handle to be used for subsequent printer operations. | ||||||||||
status-code |
Printer status code:
|
This routine is available in 32-bit environments only.
You can check the success of the call by examining RETURN-CODE.
Sets the color on the printer.
call "PC_PRINTER_SET_COLOR" using printer-handle
by value fore-or-back
by value color-red
by value color-green
by value color-blue
returning status-code
printer-handle |
pic x(4) comp-5. |
fore-or-back |
pic x(2) comp-5. |
color-red |
pic x(2) comp-5. |
color-green |
pic x(2) comp-5. |
color-blue |
pic x(2) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. | |
fore-or-back |
Whether to set foreground or background: | |
| 1 | foreground | |
| 2 | background | |
color-red |
Value between 0 and 255; intensity of red | |
color-green |
Value between 0 and 255; intensity of green | |
color-blue |
Value between 0 and 255; intensity of blue | |
None
This routine is available in 32-bit environments only.
You must open the printer before using this routine.
If your printer does not support color, it is up to the printer device driver to interpret these values. For example, some perform gray-shading; others choose either black or white for each color.
You specify the color you want by combinations of values showing the intensity of the three primary colors. For example, to get the colors in the following table, you set the RGB values as shown:
| Color | Red | Green | Blue |
| Red | 255 | 0 | 0 |
| Yellow | 255 | 255 | 0 |
| Green | 0 | 255 | 0 |
| Cyan | 0 | 255 | 255 |
| Blue | 0 | 255 | 255 |
| Magenta | 255 | 0 | 255 |
| White | 255 | 255 | 255 |
| Black | 0 | 0 | 0 |
Some other, more unusual, colors are:
| Color | Red | Green | Blue |
| Dark orange | 255 | 120 | 238 |
| Navy blue | 0 | 0 | 128 |
| Violet | 238 | 120 | 238 |
| Beige | 245 | 245 | 220 |
Sets the font on the printer.
call "PC_PRINTER_SET_FONT" using printer-handle
font-family-name
by value font-size
by value font-style
returning status-code
printer-handle |
pic x(4) comp-5. |
font-family-name |
Group item defined as: |
name-len |
x(2) comp-5. |
name-text |
pic x(). |
font-size |
Numeric literal or pic x(4) comp-5. |
font-style |
Numeric literal or pic x(4) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. | ||||||||
name-len |
The length of the font family name. | ||||||||
name-text |
The family name of the font to be used, such as Courier, Times and Symbol | ||||||||
font-size |
Point size of the font | ||||||||
font-style |
Set of bits defining the required font style:
All remaining bits are reserved for future use and should not be set. |
None
This routine is available in 32-bit environments only.
You can check the success of the call by examining RETURN-CODE.
Writes a text string to the printer.
call "PC_PRINTER_WRITE" using printer-handle
print-buffer
by value print-buff-len
returning status-code
printer-handle |
pic x(4) comp-5. |
print-buffer |
pic x(n). |
print-buff-len |
Numeric literal or pic x(4) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. |
printer-buffer |
The buffer from which the bytes are to be printed |
printer-buff-len |
The number of bytes to print |
None
This routine is available in 32-bit environments only.
You can check the success of the call by examining RETURN-CODE.
Write a loaded bitmap to a printer at a specified position with a given size.
call "PC_PRINTER_WRITE_BMP" using printer-handle
by value bmp-id
by value reserved
by value bmp-row
by value bmp-col
by value bmp-width
by value bmp-height
returning status-code
printer-handle |
pic x(4) comp-5. |
reserved |
pic x(4) comp-5 value 0. |
bmp-id |
pic x(4) comp-5. |
bmp-row |
pic x(4) comp-5. |
bmp-col |
pic x(4) comp-5. |
bmp-width |
pic x(4) comp-5. |
bmp-height |
pic x(4) comp-5. |
status-code |
See Key |
printer-handle |
The printer handle returned when the printer was opened. |
bmp-id |
The unique identifier of the bitmap to print |
bmp-row |
The position of the bitmap to print. |
bmp-width |
The size of the bitmap to print. |
status-code |
Printer status code:
|
This routine is available in 32-bit environments only.
This routine works with PostScript and HP PCL printers. It is not supported on HP Deskjet or dot matrix printers.
PC_PRINTER_FREE_BMP
PC_PRINTER_LOAD_BMP
Returns information about the status of a printer.
call "PC_TEST_PRINTER" using printer-no
printer-status
returning status-code
printer-no |
pic x comp-x. |
printer-status |
pic x comp-x. |
status-code |
See Key |
printer-no |
Number of the printer to check; must be 0, 1, or 2. Note that for LPT1, printer-no is 0, for LPT2 it is 1, and so on. |
printer-status |
A value indicating the status of the printer. For fully IBM
compatible printers, it is a combination of the following values. For other
printers, See Comments below.
|
This routine is available only in DOS environments.
This routine is only available for use with parallel printers that are local to the machine. It does not work for printers that are on a network, as these are serial printers.
You only get the correct printer-status returned if you are using an IBM PC and an IBM-compatible printer. If you are using equipment which is not 100% compatible at the BIOS level with equivalent IBM equipment, you can get different values in printer-status. A more reliable alternative is to use the run-time switch +L and check the FILE STATUS after using a WRITE statement to write to the printer.
Use this routine for determining the status of local non-spooled printers only. If the printer is spooled by the network or a local spooler, the status returned is always the same.
Note that this routine gives different results on the shared and static run-time systems. To get the same results, run the application with the P switch turned on if you are using the shared run-time system.
Executes the specified DOS interrupt.
call x"84" using interrupt-number
flag
AX-parameter
BX-parameter
CX-parameter
DX-parameter
interrupt-number |
pic x comp-x |
flag |
pic x comp-x field |
AX-parameter |
Group item defined as: |
AX-byte-hi |
pic x comp-x |
AX-byte-lo |
pic x comp-x |
BX-parameter |
Group item defined as: |
BX-byte-hi |
pic x comp-x |
BX-byte-lo |
pic x comp-x |
CX-parameter |
Group item defined as: |
CX-byte-hi |
pic x comp-x |
CX-byte-lo |
pic x comp-x |
DX-parameter |
Group item defined as: |
DX-byte-hi |
pic x comp-x |
DX-byte-lo |
pic x comp-x |
interrupt-number |
The DOS interrupt number. | ||||||||||||||||
flag |
Indicates which registers are initialized on entry, and which return values
on exit.
|
||||||||||||||||
aX-parameter |
A value to be placed in the aX register if the corresponding bit in flag is clear. |
aX-parameter |
The contents of the aX register if the corresponding bit in flag is set. |
This routine is available for use only on DOS.
This routine can be used only for interrupts that accept parameters through the AX, BX, CX, and DX registers. Any interrupt which requires support outside of this constraint, such as control of DS and ES or adjustments to the stack after the interrupt, should be accessed using an assembler subprogram.
On entry to the interrupt call, DS=ES=program address space.
The following example uses the DOS FCB interface to open a file.
* dos interrupt number=21h
01 msdos pic x comp-x value h"21".
* The contents of the parameter funct are to be placed in and
* taken from AX before and after the interrupt.
01 flag pic x comp-x value h"11".
01 funct.
02 funct-ah pic x comp-x.
02 funct-al pic x comp-x.
01 fcb.
02 filler pic x value x"00".
02 filler pic x(8) value "myfile".
02 filler pic x(3) value "dat".
02 filler pic x(25).
01 null-param pic x.
...
move 15 to funct-ah
* ah = dos function, open fcb
call x"84" using msdos
flag
funct
null-param
null-param
fcb
* al = result
if funct-al <> 0
go to file-not-found
end-if
Returns the contents of the byte at the specified memory address.
call x"85" using segment
offset
data-value
segment |
pic 9(5) |
offset |
pic 9(5) |
data-value |
pic x |
segment |
The segment you want to examine. |
offset |
The offset within the segment. |
data-value |
The contents of the byte read. |
This routine is available for use only on DOS.
X"86" - Write Byte to Memory
X"94" - Read Word from Memory
X"95" - Write Word to Memory
Writes to the byte at the specified memory address.
call x"86" using segment
offset
data-value
segment |
pic 9(5) |
offset |
pic 9(5) |
data-value |
pic x |
segment |
The segment you want to write to. |
offset |
The offset within the segment. |
data-value |
The value to be placed in the byte. |
None
This routine is available for use only on DOS.
X"85" - Read Byte from Memory
X"94" - Read Word from Memory
X"95" - Write Word to Memory
Reads a byte from a hardware port.
call x"87" using port
data-value
port |
pic 9(5) |
data-value |
pic x |
port |
The address of the port to read from. If you have the address in hexadecimal, specify as VALUE h"xxxx". |
data-value |
The value read from the port. |
This routine is available for use only on DOS.
X"88" - Write Byte to Hardware Port
X"96" - Read Word from Hardware Port
X"97" - Write Word to Hardware Port
Writes a byte to a hardware port.
call x"88" using port
data-value
port |
pic 9(5) |
data-value |
pic x |
port |
The address of the port to write to. If you have the address in hexadecimal, specify as VALUE h"xxxx". |
data-value |
The value to write to the port. |
None
This routine is available for use only on DOS.
X"87" - Read Byte from Hardware Port
X"96" - Read Word from Hardware Port
X"97" - Write Word to Hardware Port
Sets the programmable COBOL switches.
call x"91" using result
function-code
parameter
result |
pic x comp-x |
function-code |
pic x comp-x |
parameter |
Group item defined as: |
switch-flag |
pic x comp-x occurs 8 |
debug-flag |
pic x comp-x |
function |
Value 11 |
switch-flag |
The values (0 or 1) to set in switches 0 thru 7. |
debug-flag |
If set to 1, the ANSI Debug module is enabled. |
result |
Set to zero if the call was successful, nonzero otherwise. |
This routine is available for use only on DOS, Windows and OS/2.
To update one switch without affecting the others, you should read the switches with X"91" function 12, update parameter, and then call this function.
X"91" function 12 - Read Programmable Switches
Reads the programmable COBOL switches.
call x"91" using result
function-code
parameter
result |
pic x comp-x |
function-code |
pic x comp-x |
parameter |
Group item defined as: |
switch-flag |
pic x comp-x occurs 8 |
debug-flag |
pic x comp-x |
function |
Value 12 |
result |
Set to zero if the call was successful, nonzero otherwise. |
switch-flag |
The values of switches 0 thru 7. |
debug-flag |
Set to 1 if the ANSI Debug module is enabled, otherwise zero. |
This routine is available for use only on DOS, Windows and OS/2.
X"91" function 11 - Set Programmable Switches
Sets the run-time switches.
call x"91" using result
function-code
parameter
result |
pic x comp-x |
function-code |
pic x comp-x |
parameter |
pic x comp-x occurs 26 |
function |
Value 13 |
parameter |
Each byte represents one of the switch letters, each bit in a byte is the state to set the numeric switch for that letter. For example, parameter(1) bit 0 represents switch A (or A0), bit 5 of parameter(19) represents switch S5. |
result |
Set to zero if the call was successful, nonzero otherwise. |
This routine is available for use only on DOS, Windows and OS/2.
To update one switch without affecting the others, you should read the switches with Function 14, update parameter, and then call this function.
X"91" function 14 - Read Run-time Switches
Reads the run-time switches.
call x"91" using result
function-code
parameter
result |
pic x comp-x |
function-code |
pic x comp-x |
parameter |
pic x comp-x occurs 26 |
function |
Value 14 |
parameter |
Each byte represents one of the switch letters, each bit in a byte is the state of the numeric switch for that letter. For example, parameter (1) bit 0 represents switch A (or A0), bit 5 of parameter (19) represents switch S5. |
result |
Set to zero if the call was successful, nonzero otherwise. |
This routine is available for use only on DOS, Windows and OS/2.
X"91" function 13 - Set Run-time Switches
Checks for the existence of the specified program.
call x"91" using result
function-code
parameter
result |
pic x comp-x | ||||||||
function-code |
pic x comp-x | ||||||||
parameter
|
Group item defined as:
|
function |
Value 15 |
name-len |
The length of the name in filename. |
progname |
The name of the program to be looked for. This parameter must be at least 65 characters long. |
progname |
If the program is found, contains the full name. |
result |
Set to zero if the program was found, non-zero otherwise. |
This routine is available for use only on DOS, Windows and OS/2.
If the program file is found, you must then call the program, using the filename returned.
This call must not be used to check for the existence of data files; use CBL_CHECK_FILE_EXIST instead.
Shows how many of the parameters in the call statement of the calling program have been transferred to the called subprogram.
call x"91" using result
function-code
parameter
result |
pic x comp-x |
function-code |
pic x comp-x |
parameter |
pic x comp-x |
function |
Value 16 |
parameter |
The number of parameters. |
result |
Set to zero if the call was successful, nonzero otherwise. |
This routine is available for use only on DOS, Windows and OS/2.
This function is used in the called program; for the function to work in generated code, the program must be compiled with the PARAMCOUNTCHECK directive.
This function can only be used if the program is called from a COBOL program.
In certain circumstances, the number returned by the call is greater than the number of parameters transferred by the call statement of the calling program. For example:
Performs an EXEC call (like the DOS 4B call) to the specified program file, executing it.
call x"91" using result
function-code
parameter
result |
pic x comp-x |
function-code |
pic x comp-x |
parameter |
Group item defined as: |
name-len |
pic x comp-x |
progname |
pic x(n) |
function |
Value 35 |
name-len |
The number of characters in the name of the program. If this is set to zero, whatever has been previously written to the command line is executed. |
progname |
The filename of the program to be executed. |
result |
Zero if the EXEC call was successful, nonzero otherwise. If the reason for failure is an operating system error and has a number less than 255, that number is returned. Otherwise, 255 is returned. |
This routine is available for use only on DOS, Windows and OS/2.
To execute a command line instead of just a named program, set name-len
to zero, and set the command line using the DISPLAY...UPON COMMAND-LINE syntax
(see your Language Reference for details).
If this function is called from a program linked with the lcoboldw or the coblibw library (Windows default window), the EXECed program is executed in a different window (if it is a Windows application) or in a DOS session (if it is a DOS application).
If you want to execute batch (.bat) or command (.cmd) files with this routine, you must use DISPLAY...UPON COMMAND-LINE. This facility is available only on DOS and OS/2.
The following example shows how you can perform a dir/w using function 35 on DOS and OS/2:
working-storage section.
01 command-lin-string pic x(80) value "dir/w".
01 result pic x comp-x.
01 func pic x comp-x value 35.
01 command-lin.
03 command-lin-length pic x comp-x value zero.
procedure division.
main.
display command-lin-string upon command-line
call x"91" using result, func, command-lin
if result = zero
display "call worked"
else
display "call failed"
stop run
end-if
The result field in this example shows whether the command processor is invoked successfully, it does not show if the command itself is executed. The return code from the application you are trying to call is also not given.
16-bit OS/2 only:
If you use this routine to execute a new process on 16-bit OS/2 systems, you need to ensure that the new process you want to create is the same type as the process creating the process. For example, if you want to create a new Presentation Manager (PM) process then you must create it from a PM process. Note that you cannot use DISPLAY ... UPON COMMAND-LINE to create a new PM process, whether the creating process is a PM process or not.
Fixes and unfixes a program's Data Division in memory.
call X"91" using result
function-code
parameter
result |
pic x(2) comp-x. |
function-code |
pic x comp-x. |
parameter |
pic x(2) comp-x. |
function-code |
The action to perform:
|
||||
parameter |
Reserved (must be set to 0). |
result |
Contains zero if failed, else nonzero |
This routine is available for use only on DOS.
This routine is useful when interfacing with non-COBOL applications where there is a requirement that a COBOL data area should not be relocated by the RTE memory management.
Returns the contents of the word at the specified memory address.
call x"94" using segment
offset
data-value
segment |
pic 9(5) |
offset |
pic 9(5) |
data-value |
pic xx |
segment |
The segment you want to examine. |
offset |
The offset within the segment. |
data-value |
The contents of the word read. |
This routine is available for use only on DOS.
X"85" - Read Byte from Memory
X"86" - Write Byte to Memory
X"95" - Write Word to Memory
Writes to the word at the specified memory address.
call x"95" using segment
offset
data-value
segment |
pic 9(5) |
offset |
pic 9(5) |
data-value |
pic x |
segment |
The segment you want to write to. |
offset |
The offset within the segment. |
data-value |
The value to be placed in the word. |
None
This routine is available for use only on DOS.
X"85" - Read Byte from Memory
X"86" - Write Byte to Memory
X"94" - Read Word from Memory
Reads a word from a hardware port.
call x"96" using port
data-value
port |
pic 9(5) |
data-value |
pic xx |
port |
The address of the port to read from. If you have the address in hexadecimal, specify as VALUE h"xxxx". |
data-value |
The value read from the port. |
This routine is available for use only on DOS.
X"87" - Read Byte from Hardware Port
X"88" - Write Byte to Hardware Port
X"97" - Write Word to Hardware Port
Writes a word to a hardware port.
call x"97" using port
data-value
port |
pic 9(5) |
data-value |
pic xx |
port |
The address of the port to write to. If you have the address in hexadecimal, specify as VALUE h"xxxx". |
data-value |
The value to write to the port. |
None
This routine is available for use only on DOS.
X"87" - Read Byte from Hardware Port
X"88" - Write Byte to Hardware Port
X"96" - Read Word from Hardware Port
Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Integrated Preprocessor Interface |