libdcs.a — Fortran 90/95 callable interface to DCS commands.
MODULE NCAR_MSS
INTEGER(4), PARAMETER :: DCS_EXIT_LIB_INTERNAL = -1
INTEGER(4), PARAMETER :: DCS_EXIT_SUCCESS = 0
! ...
INTERFACE
SUBROUTINE dcs_name
These functions provide a convenient wrapper around the procedure
of starting the DCS command and collecting the command's output
and exit status. By including the dcs.f90 header file,
the correct types for the arguments and return values will be
automatically used regardless of the specific API (32-bit, 64-bit)
used by the application program.
The dcs_name in the synopsis is
replaced with the name of one of the DCS commands listed below:
| DCS request management commands | dcsjlog, dcsq, dcsrm and dcswait |
| Metadata commands | msallinfo, mschproj, msclass, mscomment, msdu, msfind, msls, msmv, mspasswd, mspwd, msrecover, msretention, msrm and mstouch. |
| File transfer | msrcp |
The STATUS parameter is a 32-bit
integer that holds the status of the command. See the
Return Values section below for details.
The ARGS parameter is a string of
command line arguments to be passed to the DCS command.
Pass either a character constant or a CHARACTER variable.
It is not necessary to append a zero (NUL) byte to the end
of the string.
The parsing of the ARGS parameter
proceeds as follows:
\) character.
') or a
pair of double quotes (").
Quoted characters may not be nested, but a double quote may appear
inside a pair of single quotes (or vice versa).
The OUT parameter is a CHARACTER
variable large enough to contain the command's expected
stdout stream.
If the CHARACTER variable is not large enough to contain the
output, the output will be truncated to fit within the allotted
space. If the declared CHARACTER variable is larger than the
output, the CHARACTER variable will be blank padded to the size of
the variable.
The ERR parameter is a CHARACTER
variable large enough to contain the command's expected
stderr stream.
If the CHARACTER variable is not large enough to contain the
output, the output will be truncated to fit within the allotted
space. If the declared CHARACTER variable is larger than the
output, the CHARACTER variable will be blank padded to the size of
the variable.
-1
will be returned and errno
will be set. An error message, prefixed by
ERROR detected by the DCS library:,
will appear on the stderr of the calling process.
Otherwise, the (positive) exit status of the DCS command
will be returned.
If -1 is returned,
errno will likely have been set
by one of the following library or system calls:
close(2),
dup2(2),
fork(2),
free(3),
malloc(3),
pipe(2),
read(2),
select(2), and
waitpid(2).
AIX FORTRAN USERS: Make sure you access the definition of
the NCAR_MSS module by including dcs.f90,
as this header will redefine the subroutine names to the proper
external symbol names with a trailing underscore character (_).
This will help ensure your code is portable to other operating
systems with the DCS libraries installed.
The library routines work by executing a
fork(2)
to create a child process, then
execvp(2)
to start the DCS command (which searchs along the PATH
environment variable to find them).
The stdout and stderr streams are collected by reading two pipes
and placing the output either into the appropriate user-provided
buffers or allocating and returning new buffers. The child process
is reaped with
waitpid(2).
system(3)
function, as it is not thread safe on all of the
platforms supported by DCS. Thus it is not possible to
access shell or environment variables in the command's arguments.
If the application catches the
SIGCHLD signal, it must be
prepared for signal notifications caused by the termination of
child processes started by the DCS library.
The user's application must not use the
wait(2)
system call, or the DCS library will likely hang forever
waiting for its child process.
Ensure your PATH includes the directory containing
the DCS commands.
Since the mscdsetup command is not supported by this interface, either provide absolute MSS pathnames, or execute the appropriate mscdsetup(1NCAR) and mscd(1NCAR) commands prior to invoking your application.
The compiler-specific options may vary as to how to indicate where the include and module files are kept. For example, on AIX and IRIX, the following works for 32-bit API programs (if the 32-bit API is the default):
f90 -I/usr/local/dcs-4.0/include -I/usr/local/dcs-4.0/lib32 \ -L/usr/local/dcs-4.0/lib32 -o program main.f90 -ldcs
Here is a Fortran 90 example of msls:
program main
include "dcs.f90"
use ncar_mss
integer(4) :: status
character(500) :: output
character(500) :: error
call msls(status, "-l", output, error)
print *, status
print '(A)', output
print '(A)', error
end program
Here is a more complex example of using the asynchronous feature of msrcp. In this example, we submit the msrcp request, then perform some other tasks, then wait for the msrcp request to complete. Be sure you review the msrcp man page for a complete description of using the "-async" option.
program main
include "dcs.f90"
use ncar_mss
integer(4) :: status
character(500) :: output
character(500) :: error
character(100) :: args
!...create local file "foo"...
args = "-async foo mss:/LOGIN/foo"
! The DCS job id is returned to "output"...
call msrcp(status, args, output, error)
if (status .ne. DCS_EXIT_SUCCESS) then
print *, "msrcp failed: msrcp ", args
print '(A)', error
stop
endif
! Perform other tasks
! Now wait for the msrcp to complete...
args = output
call dcswait(status, args, output, error)
! Check dcswait status
end
These the header file is located at
/usr/local/dcs-4.0/include/dcs.f90.
The (compiler specifc named) Fortran 90 precompiled module file
(.mod) and the library is
located either in the
/usr/local/dcs-4.0/lib32/libdcs.a file for
32-bit API programs, or the
/usr/local/dcs-4.0/lib64/libdcs.a file for
64-bit API programs. Some system administrators may
also provide symlinks to the header file and the libraries
in other system specific locations.
dcsjlog(1NCAR), dcsq(1NCAR), dcsrm(1NCAR), dcswait(1NCAR), msallinfo(1NCAR), mschproj(1NCAR), msclass(1NCAR), mscomment(1NCAR), msdu(1NCAR), msfind(1NCAR), msls(1NCAR), msmv(1NCAR), mspasswd(1NCAR), msrawinfo(1NCAR), msrcp(1NCAR), msrecover(1NCAR), msretention(1NCAR), msrm(1NCAR), mstouch(1NCAR).