3.10 Examples of Calling System Routines

This section provides complete examples of calling system routines from DEC C. Example 3-23 shows the three mechanisms for passing arguments to system services and also shows how to test for status return codes. Example 3-24 shows various ways of testing for successful $QIO completion. Example 3-25 shows how to use time conversion and set timer routines.

In addition to the examples provided here, the VMS Run-Time Library Routines Volume and the OpenVMS System Services Reference Manual also provide examples for selected routines. See these manuals for help on using a specific system routine.

Example 3-23 Passing Arguments to System Services

/* GETMSG.C
   This program is an example showing the three mechanisms
   for passing arguments to system services.  It also
   shows how to test for specific status return
   codes from a system service call. */

#include <stdio.h>
#include <descrip.h>
#include <ssdef.h>

int main(void)
{
int message_id;
short message_len;
char text[133];
$DESCRIPTOR(message_text, text);
register status;

while (printf("\nEnter a message number <Ctrl/Z to quit>: "),
       scanf("%d", &message_id) != EOF)
   {
   /* Retrieve message associated with the number. */
   status = SYS$GETMSG(message_id, &message_len,
                       &message_text, 15, 0);

   /* Check for status conditions. */
   if (status == SS$_NORMAL)
      printf("\n%.*s\n", message_len, text);
   else if (status == SS$_BUFFEROVF)
      printf("\nBUFFER OVERFLOW -- Text is: %.*s\n",
              message_len, text);
   else if (status == SS$_MSGNOTFND)
      printf("\nMESSAGE NOT FOUND.\n");
   else
      {
      printf("\nUnexpected error in $GETMSG call.\n");
      LIB$STOP(status);
      }
   }
}

Example 3-24 Determining $QIO Completion

/* ASYNCH.C
   This program shows various ways to determine
   $QIO completion. It also shows the use of an
   IOSB to obtain information about the I/O operation. */

#include <iodef.h>
#include <ssdef.h>
#include <descrip.h>

typedef struct
          {
          short cond_value;
          short count;
          int info;
          } io_statblk;

main(void)
{
char text_string[]  =  "This was written by the $QIO.";
register status;
short chan;
io_statblk status_block;
int AST_PROC();
$DESCRIPTOR (terminal, "SYS$COMMAND");

/*  Assign I/O channel.  */
if (((status = SYS$ASSIGN (&terminal, &chan,0,0)) & 1) != 1)
   LIB$STOP (status);

/*  Queue the I/O.  */
if (((status = SYS$QIO (1, chan, IO$_WRITEVBLK, &status_block,
          AST_PROC, &status_block, text_string,
          strlen(text_string),0,32,0,0)) & 1) != 1)
   LIB$STOP (status);

/*  Wait for the I/O operation to complete.  */
if (((status = SYS$SYNCH (1, &status_block)) & 1) != 1)
   LIB$STOP (status);
if ((status_block.cond_value &1) != 1)
   LIB$STOP(status_block.cond_value);

printf ("\nThe I/O operation and AST procedure are done.");
}

AST_PROC (io_statblk, *write_status)
io_statblk *write_status;

/* This function is called as an AST procedure. It uses
   the AST parameter passed to it by $QIO to determine
   how many characters were written to the terminal. */

{
printf("\nNumber of characters output is  %d", write_status->count);
printf("\nI/O completion status is %d", write_status->cond_value);
}

Example 3-25 Using Time Routines

/*  ALARM.C
    This program shows the use of time conversion
    and set timer routines.  */

#include <stdio.h>
#include <descrip.h>
#include <ssdef.h>

main(void)
{
#define event_flag 2
#define timer_id 3

typedef int quadword[2];

quadword delay_int;
$DESCRIPTOR(offset, "0 ::15.00");
char cur_time[24];
$DESCRIPTOR(cur_time_desc, cur_time);
int i;
unsigned state;
register status;

/* Convert offset from ASCII to binary format. */
if (((status=SYS$BINTIM(&offset, delay_int)) &1) != 1)
   LIB$STOP(status);

/* Output current time. */
if (((status=LIB$DATE_TIME(&cur_time_desc)) &1) != 1)
   LIB$STOP(status);
cur_time[23] = '\0';
printf("The current time is : %s\n", cur_time);

/* Set the timer to expire in 15 seconds. */
if (((status=SYS$SETIMR(event_flag, &delay_int,
                        0, timer_id)) &1) != 1)
   LIB$STOP(status);

/* Count to 1000000. */
printf("beginning count . . . .\n");
for (i=0; i<=1000000; i++)
   ;

/* Check if the timer expired. */
switch (status = SYS$READEF(event_flag, &state))
 {
 case SS$_WASCLR : /* Cancel timer */
                   if (((status=SYS$CANTIM(timer_id, 0)) &1) != 1)
                       LIB$STOP(status);
                   printf("Count completed before timer expired.\n");
                   printf("Timer canceled.\n");
                   break;
 case SS$_WASSET : printf("Timer expired before count completed.\n");
                   break;
 default         : LIB$STOP(status);
                   break;
 }
}