bs2cmd - execute BS2000 commands by means of the CMD macro (BS2000)

Syntax	#include <bs2cmd.h> int bs2cmd(const char *cmd, bs2cmd_rc *rc, int maxoutput, int flag0                    [, int *outbuflen, char *outbuf [, int *errbuflen, char *errbuf]]);
Description	bs2cmd() can be used to execute a BS2000 command by means of the BS2000 CMD macro. Only commands for which the CMD macro is permissible can be used. In particular, it makes no sense to execute commands that lead to the unloading of the calling program, since the interface does not include any precautionary features that prevent this. The command outputs can be buffered optionally. In this case the interface can also be used by an rlogin task without a SYSFILE environment. Description of the fixed parameter const char *cmd This parameter contains the command to be executed or a list of commands separated by semicolons. Except for strings enclosed in apostrophes, all characters are converted to uppercase letters in cmd before the call. bs2cmd_rc *rc rc is a pointer to the structure bs2cmd_rc, which contains return information. bs2cmd_rc is structured as follows: typedef struct bs2cmd rc { unsigned char subcode2; unsigned char subcode1; unsigned short maincode; unsigned short progrc; char cmdmsg[8]; } bs2cmd rc; If the NULL pointer is passed when bs2cmd is called with rc, no return information is made available. int maxoutput This parameter specifies the size of the buffer to be created for command output in bytes. When setting the buffer size you must take into account that administration information is also output in addition to the command output itself. The following constants can be specified: BS2CMD_DEFAULT A standard buffer of 256 KB is used. BS2CMD_NOBUFFER Output is not buffered. With this setting, commands that generate output can only be executed under rlogin tasks if the user provides a buffer (specification of BS2CMD_FLAG_USER_BUFFER in the parameter flag). If the buffer is set too small for the pending output, command execution is aborted. int flag This parameter specifies the interface configuration flags. The following flags and flag combinations (linked with "|") can currently be specified: BS2CMD_FLAG_STRIP The print control characters in the command output are removed before output is made. BS2CMD_FLAG_SPLIT The command outputs are split between stdout and stderr. Messages are output to stderr. BS2CMD_FLAG_USER_BUFFER bs2cmd is called with a variable parameter list. The parameters of the variable parameter list are then evaluated. These parameters must be specified completely, otherwise the behaviour of the bs2cmd function is undefined. Description of the variable parameter list The following parameters allow command outputs to be sent to a memory area provided by the user if BS2CMD_FLAG_USER_BUFFER is set in the parameter flag. int *outbuflen Length of the memory area for stdout outputs. After bs2cmd is executed, outbuflen contains the number of bytes actually written to outbuf, or -1 if outbuf is set too small for the output. char *outbuf Address of the memory area for stdout outputs. int *errbuflen Length of the memory area for stderr outputs. After bs2cmd is executed, errbuflen contains the number of bytes actually written to errbuf, or -1 if errbuf was set too small for the output. *errbuflen is only relevant if BS2CMD_FLAG_SPLIT is set in the parameter flag. char *errbuf address of the memory area for stderr outputs. *errbuf is only relevant if the BS2CMD_-FLAG_SPLIT is set in the parameter flag.
Return val.	maincode	If the command is executed successfully, errno is not set.
	-1	If an error occurs. In case of an error, the contents of the user buffer are undefined. errno is set to indicate the error.
Errors	bs2cmd() will fail if:
	EINVAL	One of the arguments has an impermissible value (e.g. an empty command or a negative buffer size).
	ENOMEM	There is not enough memory available for the buffers to be created.
	EFAULT	After the command is executed, the contents of the output buffer cannot be interpreted or there is an outbuf alignment error.
	EFBIG	The output buffer is not large enough for the outputs.
Notes	The messages are written into the memory area passed by the user and terminated with \n. Depending on the values specified in the parameter flag, the messages are either only written to outbuf or split over outbuf and errbuf, either with or without print control characters in each case. If the size of the memory area is big enough for the pending data, the output is terminated with \0. The \0 byte is not included in the returned length. If the size of the memory area is too small for the pending data, the value -1 is returned and EFBIG is set in errno. To discriminate between whether one of the user memory areas or the internal buffer is too small, the value -1 is entered in outbuflen or errbuflen if outbuf or errbuf is too small. If the value BS2CMD_NOBUFFER is specified for maxoutput and the value BS2CMD_FLAG_USER_BUFFER is simultaneously set for flag, no internal buffering is used and command outputs are sent directly to the buffer outbuf provided by the user. The structure of the outputs to outbuf is described in the "Macro Calls to the Runtime Section" manual. Caution! In the case described, the address of the memory area must be aligned to word boundaries, otherwise errno is set to EFAULT. If no buffering is used, the flag values BS2CMD_FLAG_STRIP and BS2CMD_FLAG_SPLIT are not evaluated. Specifying these values is ignored.