How to Use Them

The use of the SSO routines is best illustrated by the small example application. It opens an input SSDS, copies to output, and adds a new field combining information from two of the existing fields.The status checks normal in such an application have been omitted for clarity.

        CALL AST_INIT()			   	             ! Initialise
        CALL SSO_INIT()

        CALL SSO_ASSOCI( 'INP', 'READ', ILOC, SET, STATUS )  ! Get input and
        CALL DAT_TYPE( ILOC, TYPE, STATUS )                  ! output and
        CALL USI_ASSOCO( 'OUT', TYPE, OLOC, STATUS )         ! copy one to
        CALL HDX_COPY( ILOC, OLOC, STATUS )                  ! the other

        CALL SSO_GETNSRC( ILOC, NSRC, STATUS )               ! Any records?
        IF ( NSRC .EQ. 0 ) GOTO 99
       
        CALL SSO_CHKFLD( ILOC, 'X_CORR', XOK, STATUS )       ! Input fields
        CALL SSO_CHKFLD( ILOC, 'Y_CORR', YOK, STATUS )       ! present?

        IF (XOK.AND.YOK) THEN
          CALL SSO_CREFLD( OLOC, 'RADIUS', '_REAL', STATUS ) ! Create and 
          CALL SSO_MAPFLD( OLOC, 'RADIUS', '_REAL', 'WRITE', ! map field
                                             RPTR, STATUS )

          CALL SSO_MAPFLD( ILOC, 'X_CORR', '_REAL', 'READ',  ! Map input
                                             XPTR, STATUS )  ! fields
          CALL SSO_MAPFLD( ILOC, 'Y_CORR', '_REAL', 'READ',
                                             YPTR, STATUS )

          CALL SSO_CHKFITEM( ILOC, 'X_CORR', 'UNITS', UOK,   ! Units to 
                                                  STATUS )   ! be copied?
          IF ( UOK ) THEN
            CALL SSO_GETFITEM0C( ILOC, 'X_CORR', 'UNITS',    ! Copy units
                                          UNITS, STATUS )    ! Note extra arg
            CALL SSO_PUTFITEM0C( OLOC, 'RADIUS', 'UNITS',    ! needed when
                                      40, UNITS, STATUS )    ! writing char
          END IF                                             ! strings

          CALL PYTHAG( NSRC, %VAL(XPTR), %VAL(YPTR),         ! See below
                                %VAL(RPTR), STATUS )

          CALL SSO_UNMAPFLD( ILOC, 'X_CORR', STATUS )        ! Unmap fields
          CALL SSO_UNMAPFLD( ILOC, 'Y_CORR', STATUS )
          CALL SSO_UNMAPFLD( OLOC, 'RADIUS', STATUS )

        END IF

        CALL SSO_RELEASE( ILOC, STATUS )                     ! Free files
        CALL SSO_RELEASE( OLOC, STATUS )

        CALL SSO_CLOSE()                                     ! Shutdown. 
        CALL AST_CLOSE()

        SUBROUTINE PYTHAG( N, X, Y, R, STATUS )		     ! The action 
        REAL X(*),Y(*),R(*)
        IF (STATUS.EQ.SAI__OK) THEN
          DO I =1,N
            R(I)=SQRT(X(I)**2+Y(I)**2)
          END DO
        END IF
        END

Points to note.

• Always enclose the application in the AST/SSO_INIT and AST/SSO_CLOSE pair. These routines ensure that common blocks are explicitly initialised and shutdown. This is essential for applications running inside monoliths.

• Communication with SSO is always using the same top-level locator for each file, just like BDA.

• Allow for the possibility that the SSDS contains no sources - a common occurrence with WFC data.

• Explicitly unmapping is not actually required, but does spread the load in time and free resources quicker