Interstage Shunsaku Data Manager Application Development Guide - Microsoft(R) Windows(R) 2000/ Microsoft(R) Windows Server(TM) 2003 - - UNIX -

N.4 shunsearch2

Function

Performs searches based on input parameters and reports search results to the source invoking this function.

Syntax

#include         "libshun.h"
int     shunsearch2(
        char     *host_Name,     /* in  (1) Host name                   */
        int      Port_No,        /* in  (2) Port number                 */
        int      Reply_No,       /* in  (3) Reply start number          */
        int      Request_Cnt,    /* in  (4) Number of items to return   */
                                 /*         per request                 */
        char     *Query,         /* in  (5) Search expression area      */
        char     *Return,        /* in  (6) Return expression area      */
        char     *Reserve1,      /* in  (7) Reserved (NULL)             */
        char     *Reserve2,      /* in  (8) Reserved (NULL)             */
        int      Secure_Size,    /* in  (9) Size of returned data       */
                                 /*         storage area                */
        int      *Hit_Cnt,       /* out (10) Number of hits             */
        int      *Return_Cnt,    /* out (11) Number of response replies */
        int      *Stored_Size,   /* out (12) Size of reply data         */
                                 /*          storage area               */
        Sdsma    *Dsma,          /* out (13) Reply data storage         */
                                 /*          management array           */
        char     *Data           /* out (14) Reply data storage area    */
                                 /*          (Len=Secure_Size)          */
);

Return Value

The error code reported by this function is returned.

Value '0' is returned if the function completes normally.

The validity of the returned result cannot be guaranteed if a value other than '0' is returned.

Refer to N.7 Error Codes Output for details on error codes.

Parameters

(1) Host name

Specify the host name or IP address of the director server.

When the conductor function is to be used, specify the host name or IP address of the server where the conductor is running.

When the conductor function is not to be used, specify the host name or IP address of the server where the director is running.

The host name can be up to 24 bytes long.

(2) Port number

Specifies the number of the port that receives requests from the director server or the number of the port that receives search requests.

When the conductor function is to be used, specify the MySearchPort parameter in the conductor environment file.

When the conductor function is not to be used, specify the MySearchPort parameter in the director environment file.

(3) Reply start number

Specify from which item of found data to commence reporting. Specify a number greater than one.

(4) Number of items to return per request

Specify the maximum number of data items to be reported as the output result of this function.

Specify a number greater than one.

If a number greater than the maximum number of responses to client requests is specified, it will be superceded by this maximum limit. To find the maximum number of responses to client requests, refer to the AnsMax parameter in either the conductor environment file (if a conductor is being used) or the director environment file (if a conductor is not being used).

(5) Search expression area

Specify a pointer to the search expression area. For the search expression, specify a string that has been converted to the character code specified in CharacterCode in the director environment file. The size of the search expression area must be between 1 and 65, 535 bytes inclusive.

Refer to B.3 Search Expressions for details on search expressions.

(6) Return expression area

Specify a pointer to the return expression area. The return expression area must be allocated by the source invoking this function. The size of the return expression area must be between 0 and 65, 535 bytes inclusive.

Refer to B.4 Return Expressions for details on return expressions.

(7) Reserved

Specify NULL.

(8) Reserved

Specify NULL.

(9) Size of returned data storage area

Specifies the size of the area used to store reply data.

(10) Number of hits

Returns the number of items that match the search condition.

Zero out the area storing the number of hits before specifying this parameter.

(11) Number of response replies

Returns the number of response replies corresponding to the search results. As many reply data items as the number of response reply items will be returned to the reply data storage area.

Zero out the area storing the number of response replies before specifying this parameter.

(12) Size of reply data storage area

Returns the size of the area used to return the reply data corresponding to search results.

Zero out the area storing the size of the reply data storage area before specifying this parameter.

If the size of the returned data storage area is insufficient, the size of the area needed to store the reply data will be returned.

(13) Reply data storage management array

Sets a pointer to a reply data storage management array where the search results are returned. The reply data storage management array must be allocated by the source invoking this function.

Refer to Reply Data Storage Management Structure below for details on the reply data storage management array.

(14) Reply data storage area

Sets a pointer to a reply data storage area where the result of executing this function is returned.

Zero out the reply data storage area before specifying this parameter.

A reply data storage area equal to the size of the reply data storage area specified in (9) above must be allocated by the source invoking this function.

To obtain information about each item of reply data stored in the reply data storage area, check the pointer to and size of each item of reply data reported to the reply data storage management array.

[Reply Data Storage Management Structure]

This is a reply data storage management array structure where the results of executing this function are returned. This area must be allocated by the source invoking this function beforehand, and the size of the area must be as large as the array for the number of items to return per request.

typedef struct          /* Data storage management area            */
{
    char    *Rec_Ctl;   /* (1) Pointer to conductor control        */
                        /*     information area                    */
    char    *Rec_ID;    /* (2) Pointer to reply record identifier  */

                        /*     area                                */
    char    *Rec_Ptr;   /* (3) Pointer to reply data               */
    int     Rtn_Len;    /* (4) Size of reply data                  */
} Sdsma;

(1) Pointer to conductor control information area

Set up a pointer to the conductor control information area for the reply data in advance. Allocate a notification area in advance, and zero out this area before specifying this parameter.

Allocate a notification area equal to the length specified in COND_CTL_LEN in libshun.h.

The conductor control information is in binary format. Do not use string functions such as the str function.

(2) Pointer to reply record identifier area

Set up a pointer to the record identifier area for the reply data in advance. Allocate a notification area in advance, and zero out this area before specifying this parameter.

Allocate a notification area equal to the length specified in ROW_ID_LEN in libshun.h.

The reply record identifier is in binary format. Do not use string functions such as the str function.

(3) Pointer to reply data

The pointer to the reply data in the reply data storage area is returned after this function is called.

Zero out the area storing the pointer to the reply data before specifying this parameter.

(4) Size of reply data

The size of the reply data is returned after this function is called.

Zero out the area storing the size of the reply data before specifying this parameter.

 

The following figure shows the parameters of the shunsearch2 function.

[Figure N-4 Shunsearch2 Parameters]

• If the size of the reply data storage area exceeds the value specified in the 'size of returned data storage area' parameter, the following information will be set:
  • The size of the area needed to store data will be returned as the size of the reply data storage area.
  • The error code will be -30.
  • The data that matched the search condition (the number of hits) will be returned as the number of search hits.
  • All record identifiers that matched the search condition will be returned as reply record identifiers.
• If NULL has been set in the return expression, it will be assumed that no reply data is required, and only record identifiers will be returned.
• If the null character string '\0' or '/' is specified in the return expression, all records that matched the search condition will be returned.