RMcobol Extensions

There are a number of extensions functions for RMcobol. These are accessed via the call command. Some of these come as standard with the RMcobol run time. Others are in extension libraries that combine with the run time to add functionality.

Road Tech Computer Systems Ltd, have created a number of extension libraries for RMcobol. These are split in to two groups those done for general functionality, and those done to meet the requirements of specific customers.

The libraries are specific to the version of Roadrunner, and the operating system used. Not all functions are necessarily available on all platforms.

libRTrm
libRSArm
libDGrm

Minimum OS Cobol libRTrm libRSArm

AIX 3.x 6.xx Partial No

AIX 4.1.x 6.xx Partial No

AIX 4.2.x 7.10 Yes Yes

Linux RedHat 7.3 7.10 Yes No

Linux Fedora 3 7.10 Yes Yes

Windows 98 7.50 Yes No

AIX 4.3.x 8.01 Yes Yes

AIX 5.3.x 8.01 Yes Yes

Linux Centos 5.x 11 Yes Yes

Linux RHES 5.x 11 Yes Yes

AIX 5.3.x 12.06 Yes Yes

Minimum OS	Cobol	libRTrm	libRSArm
AIX 3.x	6.xx	Partial	No
AIX 4.1.x	6.xx	Partial	No
AIX 4.2.x	7.10	Yes	Yes
Linux RedHat 7.3	7.10	Yes	No
Linux Fedora 3	7.10	Yes	Yes
Windows 98	7.50	Yes	No
AIX 4.3.x	8.01	Yes	Yes
AIX 5.3.x	8.01	Yes	Yes
Linux Centos 5.x	11	Yes	Yes
Linux RHES 5.x	11	Yes	Yes
AIX 5.3.x	12.06	Yes	Yes

Release matrix for guiti+/runti+ (sub.c)

Original extension were for RMcobol 5.30? on AIX 3.1 only?

Function	From	runtime
SYSTEM RENAME DELETE TIMES RAND SRAND	?	Liant default fuctions
GETENV FTEST DELAY MDELAY UIDS UTOUCH	7/12/1992?	rmcobol 5.23/rmcobol 5.30
ROWCOL	18/8/1994	rmcobol 6.06?
GETPRI SETPRI NICE	18/8/1994	rmcobol 5.30?
EDIGNFILE EDIL2HOST EDIL2IP EDIF2HOST EDIF2IP	August 1996	rmcobol 6.06/rmcobol 6.61?
	21/6/1999	RMcobol 6.06 for AIX 4.1 (42283 662 runti)
	16/8/1999	RMcobol 6.61 for AIX 4.2 (26108 693 runti+)
	25/1/2001	RMcobol 6.61 for AIX 4.2 (35948 808 runvangui)
TcpOpen2Host TcpWriteln TcpWriteCrLn TcpWrite TcpReadln TcpRead TcpClose	?	Back ported from libRTrm
FileCreate FileWriteln FileWrite FileReadln FileRead FileClose	15/3/2004	Back ported from libRTrm
HttpGet	?	Back ported from libRTrm
	31/3/2006	RMcobol 6.61 for AIX 4.2 (02241 727 runti+.2006.03.31)
	05/07/2007	RMcobol 6.61 for AIX 4.2 (05949 732 runti+.2007.07.05)
	22/11/2007	RMcobol 6.61 for AIX 4.2 (17284 733 runti+.2007.11.22)
	27/8/2009	RMcobol 6.61 for AIX 4.2 (42589 732 runti+.2009.08.27)

Function matrix for libRTrm

Date	Change
200?	Forked from sub.c
2004	RT_fileCreate(), RT_fileWriteln(), RT_fileWrite(), RT_fileReadln(), RT_fileRead(), RT_fileClose(), RT_putenv()
2005?	TCP functions rewritten with an additional Parameter "Handle".
2006	RT_logLevel(), RT_stderr2file()
2006/7	Lots of changes to try and get the code working reliably on Windows.
2007	RT_writeLog(), RT_tcpWriteCrLn()
2013	Bug setting file permissions in fileCreate fixed.

Release matrix for libRTrm

RMcobol 7.10 for AIX 4.2 release 2000.

Date	Minimum OS	Min Cobol	File Size	Sum	QC	Comment
15 December 2005	Windows 98	7.50	53,248	24713 52	N/A	Superceded
6 Janiuary 2006	AIX 4.2	7.10	84,434	28170 83	N/A	Superceded
6 January 2006	AIX 4.3	8.01	96,804	11264 95	N/A	Superceded
6 January 2006	Windows 98	7.50	57,344	25080 56	N/A	Superceded
10 January 2006	Windows 98	7.50	57,344	58917 56	N/A	Superceded
19 January 2006	Windows 98	7.50	57,344	55117 56	N/A	Superceded
20 Jan 2006	AIX 4.2	7.10	89,992	06850 88	N/A	Duff
20 January 2006	AIX 4.3	8.01	193,544	37061 190	N/A	Superceded
20 January 2006	Windows 98	7.50	57,344	45693 56	N/A	Superceded
26 January 2006	RedHat 7.3	7.10	161,237	29131 158	N/A	Superceded
31 March 2006	AIX 4.2	7.10	89,950	39546 88	N/A	Superceded
31 March 2006	Windows 98	7.50	61,440	08555 60	N/A	Superceded
21 April 2006	RedHat 7.3	7.10	161,495	40396 158	N/A	Superceded
17 May 2006	Windows 98	7.50	61,440	30599 60	N/A	Superceded
2 February 2007	RedHat 7.3	7.10	161,495	40396 158	N/A	Superceded
5 February 2007	RedHat 7.3	7.10	161,471	16419 158	N/A	Current
11 July 2007	Windows 98	7.50	65,536	30971 64	N/A	Superceded
22 November 2007	Windows 98	7.50	65,536	57971 64	N/A	Current
7 December 2007	AIX 4.2	7.10	117,320	24803 115	N/A	Superceded
7 December 2007	AIX 4.3	8.01	117,856	37621 116	N/A	Superceded
7 May 2008	AIX 4.3	8.01	118,783	57205 116	N/A	Superceded
5 August 2008	AIX 4.3	8.01	94,995	56887 93	N/A	Superceded
27 August 2009	AIX 4.2	7.10	117,304	06657 115	N/A	Current
27 August 2009	AIX 4.3	8.01	118,487	53187 116	N/A	Current
9 December 2011	CentOS 5.x	11	117,576	33977 115	Pending	linux32test
13 January 2012	AIX 5.3	8.1	182,512	60552 179	Pending
13 January 2012	AIX 5.3	12.06	183,180	30160 179	Pending	aix53 test server
18 April 2012	CentOS 5.x	11	117,247	54028 115	Pending	linux32test
20 August 2012	Fedora 3	7.10	102,993	09826 101	Pending	Fedora 3 test server
14 June 2013	CentOS 5.x	11	122,176	51306 120	Pending
		11			Pending

64 bit AIX Systems

Use the same file as for a 32bit install.

It just works. :-)

64 bit Linux Systems

The COBOL run time is complied 32bit. This works fine in general on the corresponding 64 bit install of the operating system.

You do however need to make sure that you have the 32bit versions, of key libraries installed, as well as their 32bit versions. Run the command below and compare the output.

ldd /usr/bin/runcobol /usr/bin/rmcobolso/libRTrm.so /usr/bin/rmcobolso/libRSArm.so /usr/bin/rmcobolso/libDGrm.so

/usr/bin/runcobol:
        linux-gate.so.1 =>  (0x00ba6000)
        libnsl.so.1 => /lib/libnsl.so.1 (0x00496000)
        libpthread.so.0 => /lib/i686/nosegneg/libpthread.so.0 (0x00724000)
        libdl.so.2 => /lib/libdl.so.2 (0x0071d000)
        libc.so.6 => /lib/i686/nosegneg/libc.so.6 (0x005bf000)
        /lib/ld-linux.so.2 (0x0059b000)
/usr/bin/rmcobolso/libRTrm.so:
        linux-gate.so.1 =>  (0x00670000)
        libncurses.so.5 => /usr/lib/libncurses.so.5 (0x007cc000)
        libc.so.6 => /lib/i686/nosegneg/libc.so.6 (0x00daa000)
        libdl.so.2 => /lib/libdl.so.2 (0x00547000)
        /lib/ld-linux.so.2 (0x0059b000)
/usr/bin/rmcobolso/libRSArm.so:
        linux-gate.so.1 =>  (0x008ee000)
        libncurses.so.5 => /usr/lib/libncurses.so.5 (0x00cbd000)
        libc.so.6 => /lib/i686/nosegneg/libc.so.6 (0x00116000)
        libdl.so.2 => /lib/libdl.so.2 (0x00f33000)
        /lib/ld-linux.so.2 (0x0059b000)
/usr/bin/rmcobolso/libMQrm.so:
        linux-gate.so.1 =>  (0x0047e000)
        libncurses.so.5 => /usr/lib/libncurses.so.5 (0x00e8b000)
        libc.so.6 => /lib/i686/nosegneg/libc.so.6 (0x008e2000)
        libdl.so.2 => /lib/libdl.so.2 (0x00110000)
        /lib/ld-linux.so.2 (0x0059b000)

32bit Windows Systems

Current version has been confirmed to work on

MS Windows 95.
MS windows 98.
MS Windows Me.
MS Windows 2000.
MS Windows XP (32bit).
MS windows Vista(32bit).
MS Windows 7 (32bit).

64 bit Windows Systems

Not sure about all 64 bit versions of Windows, but there are definitely issues with some versions.

Reported error is can not load 16 bit driver.

Windows7 64 bit. Snag is that libRTrm.dll is not supposed to be a driver, and the compiler said it was compiling 32bit, the file header also marks it as a 32bit file. Suspect that the issue is with a system DLL, that it depends on, but sorting out which one and if you can work around the issue is problematic.

RMcobol standard System Calls

These are available on virtually all systems.

SYSTEM

RENAME

DELETE

RAND

SRAND

Roadtech extensions for use with Roadrunner

Available integrated with the run time for RMcobol 6.xx, or as a shared library module for RMcobol 7xx, 8xx, ...

These have generally been ported to AIX 3.2.5, 4.1.x, 4.2.x, 4.3.x, SCO ?

Roadtech RMcobol extensions {logging}

Logging problems has been an issue over the years. Especially when using the vangui extension libraries, as these close all file handles when they initialize.

There are platform dependent restrictions, as to what options are available for logging.

With most supported systems, there is a configurable system wide logging daemon. usually syslog, or rsyslog. This is accessed via the openlog, syslog, and closelog functions.

Unfortunately there is no direct equivalent for DOS/Windows. As a result of this the behavior varies depending on the platform and run time version.

Windows RMcobol >= 8.10	display a message box
Windows or DOS, RMcobol <= 7.xx	Output to file stderr.wri in the current directory
AIX, Linux, with a controling terminal	stderr
AIX, Linux, without a controling terminal	syslog

RT_logLevel

Sets the logging level between 0 and 7.

A level of 7 causes all log messages to be handled, while a level of 0, causes most messages to be silently discarded.

        03      Log_Level       pic 9999 comp-1.

        call RT_LogLevel using ENV_NAME ENV_VAL

RT_stderr2file

Associate the file handle corresponding to stderr with a file.

        call RT_stderr2file

The above example associates standard error with the file "stderr.wri". Alternativly you may pick a file name of your choice.

        03      Log_File       pic X(64).

        call RT_stderr2file using Log_File

RT_writeLog

Write an arbitrary message to the current log destination. Message will only be written if the current log level is greater or equal to the level specified for the message.

        03      Log_Level       pic 9999 comp-1.
        03      Log_Message     pic X(64).

        call RT_writeLog using Log_Level Log_Message

Roadtech RMcobol extensions {core}

GETENV

Returns the value of an environment variable. If the variable is undefined returned string will be spaces.

        03      ENV_NAME        pic X(n)
        03      ENV_VAL         pic X(n)

        call GETENV using ENV_NAME ENV_VAL

FTEST

Checks type ahead buffer to see if any keys have been pressed.

        03      KEY_VAL         9999 comp-1.

        call FTEST using KEY_VAL

DELAY

Suspends process for a delay of WAIT seconds, or until and event occures.

        03      WAIT            pic 9(4) comp-1.
        
        move 30 to WAIT.
        call DELAY using WAIT.

UIDS

Returns the efective, real, saved and login UID's of the current process.

        03      UID_E           pic 9(4) comp-1.
        03      UID_R           pic 9(4) comp-1.
        03      UID_S           pic 9(4) comp-1.
        03      UID_L           pic 9(4) comp-1.

        Call UIDS using UID_E UID_R UID_S UID_L

UTOUCH

attempts to create the file "NAME". The file is created using the current REAL rather than the current EFECTIVE UID. This means that a user would still have access rights to this file after exiting from roadrunner. This is useful for generating output files for use with other packages.

        03      NAME            pic X(n).
        03      ERR             pic 9(4) comp-1.

        call UTOUCH using NAME ERR.

ROWCOL

Prototype workaround for bug in Version 6.00 beta run time. To obtain new screen dimensions following a screen type switch {SET 132-COLUMNS to TRUE}, {SET 80-COLUMNS to TRUE}. Please call via RRSCRDIM.PRC, as it will then be easy to take account of any changes when Liant catch up with this bugget.

        03      M-ROW            pic 9(4) comp-1.
        03      M-COL            pic 9(4) comp-1.

        call ROWCOL using M-ROW, M-COL.

MDELAY

Suspends process for a delay of WAIT mili-seconds, or until an event occurs. The higher the number the lower the priority.

        03      WAIT            pic 9(4) comp-1.
        call DELAY using WAIT.

GETPRI

Returns the current scheduling priority of the current process.

        03      PRI            pic 9(4) comp-1.
        call GETPRI using PRI.

SETPRI

Sets the current scheduling priority of the current process. Note you cannot increase your priority this way. Only select a new absolute value of lower or equal priority.

As there is no way to restore the original priority this generally only makes sense, when used in a program called for batch processing by cron or an event handler.

        03      PRI            pic 9(4) comp-1.
        call SETPRI using PRI.

NICE

Reduces the scheduling priority of the calling process by an amount "PRI".

As there is no way to restore the original priority this generally only makes sense, when used in a program called for batch processing by cron or an event handler.

        03      PRI            pic 9(4) comp-1.
        call NICE using PRI.

PUTENV

Adds a new entry to the environment, or replaces an existing entry.

Caution when replacing an entry the memory used for the previous entry is not reclaimed. Under no circumstances may programs make repeated changes to environment variables.

        03      ENV_NAME        pic X(n)
        03      ENV_VAL         pic X(n)
        
        call PUTENV    using ENV_NAME ENV_VALUE;
                ON EXCEPTION MOVE "PUTENV not supported" TO ENV-VAL.

PID

Returns the PID of the current process.

On AIX 3.1, 3.2, 4.1, 4.2 pid is a 32bit number. From AIX 4.3 onwards it may be a 64bit number depending on the setup.

        03      PID_VALUE            pic 9(18) comp-4.
        
        call PID    using PID_VALUE;
                ON EXCEPTION MOVE "PID not supported" TO ENV-VAL.

Roadtech RMcobol extensions {EDI}

These provide access from COBOL to the EDI functions provided by

rredi
edid

They use the following variables for their calls.

        03   NAME                     pic X(256).

        03   TAG.
             05     TAG_Dataset       pic X.
             05     TAG_Company       pic X.

        03   EDI-LINE.
             05 line-type.
                 07 line-basetype       pic X(3).
                 07 line-subtype       pic X .
             05 line-ver               pic 9(2).
             05 line-data.
                 07     Filler          pic X(1018).

        03   FILE    pic X(256).

        03   HOST              PIC X(40).

        03      IP      pic X(15).

        03      ERR     pic 9(4) comp-1.
                88      NOFILE  value   100.
                88      NOHOST  value   200.
                88      NOIP    value   201.
                88      NOROUTE value   202.
                88      NOPORT    value   203.
                88      NOSOCKET  value   204.
                88      NOCONNECT value   205.
                88      NOPEER    value   206.
                88      EDI_WRITE value   207.
                88      TCP_CLOSE value   208.
                88      EDI_READ  value   209.
                88      TIME_OUT  value   210.
                88      TAGERR  value   300.

EDIGNFILE

Returns the name of the file where rredid is storing incoming messages and, trips a name change so that future messages are routed to a new file.

           MOVE "ZA" to tag
           MOVE 0 to ERR.
           MOVE SPACES to ENV-VAL.
           call EDIGNFILE using NAME TAG ERR;
                ON EXCEPTION MOVE "EDIGNFILE not supported" TO ENV-VAL.

EDIL2HOST

As per rredi but from COBOL.

           Move "editest.roadrunner.uk.com" to HOST
           MOVE "ZA" to tag
           MOVE SPACES to  EDI-LINE.
           Move "TEST" to  line-type.
           Move 00 to  line-ver.
           Move "Test message" to  line-data.

           MOVE SPACES to ENV-VAL.
           MOVE 0 to ERR.

           CALL "EDIL2HOST" USING EDI-LINE, TAG, HOST, ERR;
                ON EXCEPTION MOVE "EDIL2HOST not supported" TO ENV-VAL.

EDIL2IP

As per rredi but from cobol.

        call EDIL2IP   using LINE TAG IP ERR;
                ON EXCEPTION MOVE "EDIL2IP not supported" TO ENV-VAL.

EDIF2HOST

As per rredi but from COBOL.

        call EDIF2HOST using FILE TAG HOST ERR;
                ON EXCEPTION MOVE "EDIF2HOST not supported" TO ENV-VAL.

EDIF2IP

As per rredi but from COBOL.

        call EDIF2IP   using FILE TAG IP ERR;
                ON EXCEPTION MOVE "EDIF2IP not supported" TO ENV-VAL.

File bits for Paul

Example call arguments.

        03   PATH              PIC X(400).

        03   PERM           PIC 9(4) comp-1.

        03      ERR     pic 9(4) comp-1.
                88      NOFILE    value   100.
                88      NOHOST    value   200.
                88      NOIP      value   201.
                88      NOROUTE   value   202.
                88      NOPORT    value   203.
                88      NOSOCKET  value   204.
                88      NOCONNECT value   205.
                88      NOPEER    value   206.
                88      EDI_WRITE value   207.
                88      TCP_CLOSE value   208.
                88      EDI_READ  value   209.
                88      TIME_OUT  value   210.
                88      TAGERR    value   300.

	03   Buffer		PIC x(4000).

	03   size	pic 9(4) comp -1.

Call set works with a single connection. Close the connection before attempting to open another.

FileCreate

Creates and opens a file.

        move 0 to ERR.
        move "/var/www/pub/somewhere/pic.png" to PATH.
        move 0 to PERM.
	call FileCreate using PATH, PERM, ERR;
                ON EXCEPTION MOVE "FileCreate not supported" TO ENV-VAL.

The second argument PERM in the example above, affects the permission assigned to the file that is created. the exact behavior is operating system dependent.

The value 0 sets a default set of permissions.

AIX

The effective UID is set to the Real UID before the file is created. In this way the call is similar to UTOUCH above. Also note the current value of UMASK has no effect.

perm = (S_IRWXU | S_IRWXG); which corresponds to
-rwxrwx---

That is file is readable, writable, and executable, by the real user id of the creating process, and by members of the default group. Group ID will be the effective GID the current process, unless the group sticky bit of the containing directory is set. In which case the file will be created with the same group as the directory.

Linux

Windows

perm = (_S_IREAD | _S_IWRITE)

If PERM is not 0 the the value supplied is used. Value provided should be the sum of the values for the individual permissions required.

value	AIX/Linux
1	S_IEOTH Execute by other
2	S_IWOTH write by other
4	S_IROTH read by other
8	S_IEGRP Execute by group
16	S_IWGRP write by group
32	S_IRGRP read by group
64	S_IEUSR Execute by owner
128	S_IWUSR write by owner
256	S_IRUSR read by owner
512	S_ISVTX saved swapped text after use
1024	S_ISGID Set group ID on execution
2048	S_ISUID Set user ID on execution
4096

So on AIX to create a file that is readable and writable by you, and readable by people in the group we want 32+128+256 = 416

Exit values.

On exit, ERR is not 0 if a problem occurred. On successful creation, the file handle is returned in PERM.

FileWriteln

Writes a text variable or structure to the socket appending a line feed.

If structure contains a null this will terminate the line.

Trailing space is removed, remaining line is sent.

If specified, grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used.

	move 0 to ERR.
	move "What ever we like.         " to Buffer.
	call FileWriteln using Buffer, ERR;       
                ON EXCEPTION MOVE "FileWriteln not supported" TO ENV-VAL.

or alternatively

	move 30 to grace.
	move 0 to ERR.
	move "What ever we like.         " to Buffer.
	call FileWriteln using Buffer, ERR, grace;       
                ON EXCEPTION MOVE "FileWriteln not supported" TO ENV-VAL.

FileClose

Close's open tcp socket.

	move 0 to ERR.
	call FileClose using ERR;
                ON EXCEPTION MOVE "FileClose not supported" TO ENV-VAL.

FileWrite

BlockWrite of a data structure to the file. When called Size should indicate how much of the structure is to be sent.

size <= 0, send whole structure.
size > structure size, send structure size bytes.
other wise, send size bytes.

If specified grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used..

	move "What ever we like." to Buffer.
	move 0 to ERR.
	move 18 to size. 

	call FileWrite useing Buffer, ERR, size;       
                ON EXCEPTION MOVE "FileWrite not supported" TO ENV-VAL.

or alternatively

	move "What ever we like." to Buffer.
	move 0 to ERR.
	move 18 to size. 
	move 30 to grace.

	call FileWrite using Buffer, ERR, size, grace;       
                ON EXCEPTION MOVE "FileWrite not supported" TO ENV-VAL.

On exit size is the number of bytes actually sent.

FileReadln

Read bytes from link up to the next LF on the input stream, or the timer expires, or upto the size of the buffer if no LF reached before buffer is full.

Time limit
Size of Structure provided
Line feed.

If specified grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used..

	move 0 to ERR.
	call FileReadln using Buffer, ERR;       
                ON EXCEPTION MOVE "FileReadln not supported" TO ENV-VAL.

	DISPLAY Buffer.

or alternatively

	move 30 to grace.
	move 0 to ERR.
	call FileReadln using Buffer, ERR, grace;       
                ON EXCEPTION MOVE "FileReadln not supported" TO ENV-VAL.
	DISPLAY Buffer.

Return, Structure {space filled?}, bytes read, and status.

FileRead

Attempt to read block of bytes from link. Size is the amount we wish to read, it may not exceed the size of the call structure.

size=0 implies read up to the size of the Buffer.

If specified grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used..

	move 0 to ERR.
	call FileRead using Buffer, ERR, size;       
                ON EXCEPTION MOVE "FileRead not supported" TO ENV-VAL.

	DISPLAY Buffer.

or alternatively

	move 30 to grace.
	move 0 to ERR.
	move 20 to size.
	call FileRead using Buffer, ERR, size, grace;       
                ON EXCEPTION MOVE "FileRead not supported" TO ENV-VAL.

	DISPLAY Buffer.

On return size indicated the number of bytes actually read.

TCP/IP bits for Paul

Note there are significant differences between the Pre 2007 versions, and the post 2007 version of these commands.

Example call arguments.

        03   HANDLE            pic 9(4) comp-1.

        03   HOST              PIC X(40).
        
        03   HINT              PIC X(40).
        
        03   SERVICE           PIC X(10).

        03      ERR     pic 9(4) comp-1.
                88      NOFILE    value   100.
                88      NOHOST    value   200.
                88      NOIP      value   201.
                88      NOROUTE   value   202.
                88      NOPORT    value   203.
                88      NOSOCKET  value   204.
                88      NOCONNECT value   205.
                88      NOPEER    value   206.
                88      EDI_WRITE value   207.
                88      TCP_CLOSE value   208.
                88      EDI_READ  value   209.
                88      TIME_OUT  value   210.
                88      TAGERR    value   300.

	03   Buffer		PIC x(40).

	03   size	pic 9(4) comp -1.

TCPOPEN2HOST

Given a host name attempts to open connection to server. Call works the same as my connection test utility, and my "C" library function.

It is expected that HOST will be a name resolvable by the "C" resolver library, from either DNS or a local hosts file. (Note an IPv4 address in doted quad form will also work. Routine will function correctly in the case where DNS returns multiple IP addresses.

Hint is expected to be an IPv4 address saved from a preceding run. In the event that the call fails to open the connection to the value specified by "HOST", it will try this value as well. Saving an IPv4 address from a preceding successful connection, guards against DNS faults. (Note may also be an alternate host name, but that will not protect against resolution issues.

        move 0 to ERR.
        move "pop3.roadrunner.uk.com" to HOST.
        move "pop3" to SERVICE.
	call TcpOpen2Host useing HANDLE, HOST, HINT, SERVICE, ERR;
                ON EXCEPTION MOVE "TcpOpen2Host not supported" TO ENV-VAL.

Return values

ERR set to indicate any problem that was encountered.

If call was successful, HANDLE is set to reference the connection. HINT is set to the IPv4 address of the host to which the connection succeeded, in doted quad format.

TcpWrite

Block Write of a data structure to the tcp link. Handle shall be the value returned from a successful call to TcpOpen2Host. Buffer shall be a COBOL structure containing the data to be written. Size should indicate how much of the structure is to be sent.

size <= 0, send whole structure.
size > structure size, send structure size bytes.
other wise, send size bytes.

If specified grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used..

	move 0 to ERR.
        move "What ever we like." to Buffer.
        move 18 to size. 
	call TcpWrite useing Handle, Buffer, ERR, size;       
                ON EXCEPTION MOVE "TcpWrite not supported" TO ENV-VAL.

or alternatively

	move 30 to grace.
	move 0 to ERR.
        move "What ever we like."to Buffer.
        move 18 to size. 
	call TcpWrite using Handle, Buffer, ERR, size, grace;       
                ON EXCEPTION MOVE "TcpWrite not supported" TO ENV-VAL.

Return values

On exit ERR set to indicate any problems.

On exit size is the number of bytes actually sent.

TcpWriteln

Writes a text variable or structure to the socket appending a line feed. Handle shall be the value returned from a successful call to TcpOpen2Host. Buffer shall be a COBOL structure containing the data to be written. Size should indicate how much of the structure is to be sent.

Note if structure contains a null, this will terminate the line.

Structure truncated at the indicated size, then any trailing space is removed, remaining line is sent.

size < 0, send whole structure.
size = 0, send "LF".
size > structure size, send structure size bytes.
other wise, send size bytes.

If specified grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used..

	move 0 to ERR.
        move "What ever we like.         " to Buffer.
	call TcpWriteln using Handle, Buffer, ERR, size;       
                ON EXCEPTION MOVE "TcpWriteln not supported" TO ENV-VAL.

or alternatively

	move 30 to grace.
	move 0 to ERR.
        move "What ever we like.         " to Buffer.
	call TcpWriteln using Handle, Buffer, ERR, size, grace;       
                ON EXCEPTION MOVE "TcpWriteln not supported" TO ENV-VAL.

Return values

On exit ERR set to indicate any problems.

On exit size is the number of bytes actually sent.

TcpWriteCrln

Writes a text variable or structure to the socket appending a carriage return and a line feed. Handle shall be the value returned from a successful call to TcpOpen2Host. Buffer shall be a COBOL structure containing the data to be written. Size should indicate how much of the structure is to be sent.

Note if structure contains a null, this will terminate the line.

Structure truncated at the indicated size, then any trailing space is removed, remaining line is sent.

size < 0, send whole structure.
size = 0, send "CRLF".
size > structure size, send structure size bytes.
other wise, send size bytes.

If specified grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used..

	move 0 to ERR.
        move "What ever we like.         " to Buffer.
	call TcpWriteCrln using Handle, Buffer, ERR, size;       
                ON EXCEPTION MOVE "TcpWriteln not supported" TO ENV-VAL.

or alternatively

	move 30 to grace.
	move 0 to ERR.
        move "What ever we like.         " to Buffer.
	call TcpWriteln using Handle, Buffer, ERR, size, grace;       
                ON EXCEPTION MOVE "TcpWriteln not supported" TO ENV-VAL.

Return values

On exit ERR set to indicate any problems.

On exit size is the number of bytes actually sent.

TcpRead

Attempt to read block of bytes from link. Size is the amount we wish to read, it may not exceed the size of the call structure.

size=0 implies read upto the size of the Buffer.

If specified grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used..

On return size indicates the number of bytes actually read.

	move 0 to ERR.
	call TcpRead using Handle, Buffer, ERR, size;       
                ON EXCEPTION MOVE "TcpRead not supported" TO ENV-VAL.

	DISPLAY Buffer.

or alternatively

	move 30 to grace.
	move 0 to ERR.
	move 20 to size.
	call TcpRead using handle, Buffer, ERR, size, grace;       
                ON EXCEPTION MOVE "TcpRead not supported" TO ENV-VAL.

	DISPLAY Buffer.

This is not quite right if timer expires we may only have read a partial block.

TcpReadln

Read bytes from link up to the next LF on the input stream, or up to the size of the buffer if no LF reached before buffer is full.

Time limit
Size of Structure provided
Line feed.

Return, Structure {space filled?}, bytes read, and status.

If specified grace is the maximum amount of time to block, if not specified a default value of 30 seconds is used..

	move 0 to ERR.
	call TcpReadln using handle, Buffer, ERR;       
                ON EXCEPTION MOVE "TcpReadln not supported" TO ENV-VAL.

	DISPLAY Buffer.

or alternatively

	move 30 to grace.
	move 0 to ERR.
	call TcpReadln using Handle, Buffer, ERR, grace;       
                ON EXCEPTION MOVE "TcpReadln not supported" TO ENV-VAL.
	DISPLAY Buffer.

TcpClose

Close's open tcp socket.

	move 0 to ERR.
	call TcpClose using Handle, ERR;
                ON EXCEPTION MOVE "TcpClose not supported" TO ENV-VAL.

HTTP

These HTTP methods provide a simplified interface for opening, HTTP connections. One opened use the read, write, close calls to transfer the page.

	03 HTTP_version pic X(20).
        03 HTTP_status pic 9(4) comp-1.
        03 HTTP_server_message pic X(80).
	03 HTTP_realm  pic X(20).
	03 HTTP_userid pic X(10).
	03 HTTP_passwd pic X(10).

HTTP_version Version ID returned from the server.
HTTP_status Numeric status code from server.
HTTP_server_message Short message corresponding to status.
HTTP_realm Identifier returned when Basic Authentication is required.

HttpHead

HttpGet

Negotiate http get method with server.

Question what information if any from the servers headers do we want to return to the calling program.

        move "www.ooo.xxx" to host.
        move "faq/rmcalls.html" to url.
	move 0 to ERR.
	call HttpGet using host, url, ERR, user, passwd,
                HTTP_version,
                HTTP_status,
                HTTP_server_message;
                ON EXCEPTION MOVE "HttpGet not supported" TO ENV-VAL.

On exit ERR is non zero if a problem prevents the request from being made.

HTTP_version is initialized the to server ID string.

HTTP_Status is set to the server status for the request {200 successful, 403 Access denied, ...}

HTTP_server_message is initialized to the status message from the server.

If successful the data-link is initialized at the start of the content block. Successive calls to ______Read may be made to read the contents of the "file".

HttpPut

Put New or Replacement file to server.

HttpPost

HttpReadHeader

Read one line from the set of headers returned on the last Get, Head, ...

	move 0 to ERR.
	call HttpReadHeader using header, ERR;
                ON EXCEPTION MOVE "HttpReadHeader not supported" TO ENV-VAL.

Dangerous goods functions for Patrick

This is a draft so do not take as gospel.

Draft routines are done as RMcobol 7.xx extension library.

All COBOL calls are to start "DG_" so as to avoid clashes with outer modules.

READDGSHIPING

The user at Patrick's is expected to provide the base UN number, Each UN number can apply to more than one item, and form of packing.

Think of Paraffin, it can be shipped as bulk liquid, 40 Gallon drums, or 4.5 liter plastic bottles in cardboard cartons.

So we need to read the shipping description database to identify the exact item and form of packing.

READDGSHIPING snag, call returns a linked list. we therefore need two calls 1> Call to initialize the list for a given unno 2> Call to read entry from list We can either return a count on the first call, or a flag indicating more to read on each subsequent call.


 03 unno pic S9(7) usage comp-4.  {NBS2 type 11}
 03 found pic A.        {ABS type 18 J-left}

 move 1203 to unno

 call DG_InitShippingList using unno, found.

 if found == 'N' Then display "unno not found in database"
 if found == 'Y' Then display "unno found in database"
 if found == 'E' Then display "Error accessing un database for unno"

 03 
   05 name pic X(60).   {ANS type 16 J-left, type 17 J-right}
   05 unsub pic X(4).
   05 ununique pic S9(7) usage comp-4. 

 03 more pic A.    {ABS type 18 J-left}

 call DG_ReadShippingList using name, unsub, ununique, more.

 if more == 'E' Then display "Error accessing database or attempt to read past end"

 display name
 display unsub
 display ununique

 if more == 'N' Then display "This is the last record"
 if more == 'Y' Then display "More records exist in the database"

ReadDGMaster

Once the user has identified the product and it packing we can read the master record for the identified


 03 
   05 unno pic S9(7) usage comp-4. 
   05 unsub pic X(4).
   05 ununique pic S9(7) usage comp-4. 

 03 dgdata
   05 shippingName pic X(60).
   05 class     pic X(4). 
   05 classColumn pic S9(7) usage comp-4.
   05 subrisk1  pic X(4).
   05 subrisk1Column pic S9(7) usage comp-4.
   05 subrisk2  pic X(4).
   05 subrisk2Column pic S9(7) usage comp-4.
   05 hazchen   pic X(5).
   05 hazchen   pic X(5).
   05 pkgrp1    pic X(3).
   05 pkgrp2    pic X(3).
   05 pkgrp3    pic X(3).
   05 epg       pic X(8).
   05 wmsgrp    pic X(2).
   05 printMsg	pic X(22).

 03 stat pic A. {ABS type 18 J-left}


  call DG_ReadMaster using unno unsub ununique shippingName class classColumn subrisk1 subrisk1Column subrisk2 subrisk2Column hazchen pkgrp1 pkgrp2 pkgrp3 epg wmsgrp printMsg stat

if stat == 'N' then display "Oops no record for that code"
if stat == 'Y' then display "Details for unique item found"
if stat == 'E' then display "Error accessing database."

*/ /* --------------------------------------------------------------------

DGcomp

We need an interface to call DGcomp to check Class compatibility.

For this we need to assemble an array of from 1 to 16 Class codes.

These are 4byte alphanumberic plus null termination, unused enteries are to be set to ????

17th entery is new class?

The function call returns a 4 character message code :-

                '0001' File access error
                '0010' Invalid Class code in position X1
                '0011' Incompatible Classes in position X1 and X2
                        may not be combined in a shipment
                '0012' No problems found but check on sub risks.
                '1001'-'1008' acknolageable problem.

        int index of first incompatible class code.
        int index of 2nd incompatible entery
        char ERRFLAG {' ', 'E'}

The example program at Patrick's, does not use the new class field.... It erases array to spaces, and then loads the supplied class codes into the class array.

The function is then called repetedly until it returns with ERRFLAG set to E or final is set to Y..... ?????

03 DG-CLassArray
  05 ClassCode pic X(4) occurs 16.

03 DG-StatusCode pic X(4).
03 DG-Index1 pic 9999 comp-1.
03 DG-Index2 pic 9999 comp-1.

call DG_compat_init using DG-CLassArray

call DG_compat_readMessage using DG-StatusCode,
			DG-Index1. DG-Index2, more.

Fatal :-
0001 Call support - Could not read Class table?\n
0010 printf("Class %4.4s is invalid\n", &classArray[err1No-1]);

Error :-
0011 printf("Class %4.4s and %4.4s are not compatible %4.4s\n", &classArray[err1No-1], &classArray[err2No-1], errorCode);

Warning :-
1001 printf("Class %4.4s and %4.4s - Check Note 1\n", &classArray[err1No-1], &classArray[err2No-1]);
1002 "
1003
..
1008
???? printf("Class %4.4s and %4.4s - unknown error 
%4.4s\n", &classArray[err1No-1], &classArray[err2No-1], &errorCode);
                                  printf("Call Support now\n");

??? :-
0012 printf("Compatible but check the sub risks\n");