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

N.6 shunsort

Function

This method performs searches based on input parameters and sorts or aggregates the search results before reporting them to the source invoking this function.

Syntax

#include         "libshun.h"
int     shunsort(
        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     *Sort,            /* in  (7) Sort expression area     */
        int      Secure_Size,      /* in  (8) Size of returned data    */
                                   /*         storage area             */
        int      *Hit_Cnt,         /* out (9) Number of hits           */
        int      *Return_Cnt,      /* out (10) Number of response      */
                                   /*          replies                 */
        int      *Available_Cnt,   /* out (11) Number of possible      */

                                   /*          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 server where the conductor is running.

The host name can be up to 24 bytes long.

(2) Port number

Specify the MySearchPort parameter in the conductor 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.

If a number greater than the maximum number of responses to client requests (specified in AnsMax in the conductor environment file) is specified, it will be superceded by this maximum limit.

(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 conductor 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 must be between 1 and 65,535 bytes inclusive.

If the return expression includes an aggregation function, results will be aggregated before they are returned.

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

(7) Sort expression area

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

Refer to B.5 Sort Expressions for details on sort expressions.

(8) Size of returned data storage area

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

(9) 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.

(10) 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.

(11) Number of possible replies

If a sort request is made, the number of replies that can be returned will be returned as the sort result. Up to 1,000 items can be returned. As the total length of the sort keys increases, the number of replies that can be returned decreases. Refer to Appendix C Allowable Values for the relationship between the total length of the sort keys and the total number of replies that can be returned.

If an aggregation request is made, the number of groups that can be returned will be returned as the aggregation result. Up to 1,000 groups can be returned. As the total length of the group keys increases, the number of groups that can be returned decreases. Refer to Appendix C Allowable Values for the relationship between the total length of the group keys and the total number of groups that can be returned. Zero out the area storing the number of replies that can be returned 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 returned data storage area specified in (8) 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.

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.

Do not specify the record identifiers and conductor control information returned by aggregation requests when executing the shunsearch3 function. Doing so will return no records.

(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.

Do not specify the record identifiers and conductor control information returned by aggregation requests when executing the shunsearch3 function. Doing so will return no records.

(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 for the size of the reply data before specifying this parameter.

The following figure shows the parameters of the shunsort function.

[Figure N-8 Shunsort 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.
  • With sort requests, all record identifiers that matched the search condition will be returned to the conductor control information area and the reply record identifier area.
  • With aggregation requests, the conductor control information area and the reply record identifier area remain in the same state as when the function was invoked.
• If NULL has been set in the return expression for the sort request, it will be assumed that no reply data is required and only conductor control information and record identifiers will be returned.
• If the null character string '\0' or '/' is specified in the return expression for the sort request, all records that matched the search condition will be returned.
• Aggregation requests require both a return expression area and a sort expression area.
• A conductor is required to use this function.