ProSort는 C 함수의 형태로 API를 제공한다. 모든 함수는 반환값을 가지며, 성공할 경우에는 0을 반환하고 실패할 경우에는 음수 값을 반환한다.

API로 제공되는 함수는 다음과 같다.

함수 설명

prosort_run_script

스크립트(script)의 연산을 모두 수행하는 함수이다.

prosort_setup

ProSort 실행에 필요한 정보를 초기화한다.

prosort_setup_with_userexit

모든 입출력 파라미터가 prosort_setup 함수와 동일하다.

prosort_release_record

SORT 연산을 할 때 데이터를 레코드별로 입력하는 함수이다.

prosort_release_end

SORT 연산을 할 때 데이터 입력이 끝났음을 나타내는 함수이다.

prosort_return_record

연산의 결과를 레코드 건별로 가져오는 함수이다.

prosort_end

모든 연산에 사용한 리소스를 반환하는 함수이다.

prosort_get_error_number

에러가 발생했을 때 에러 번호를 가져오는 함수이다.

prosort_get_error_message

에러가 발생했을 때 에러 메시지를 가져오는 함수이다.

1. prosort_run_script

스크립트(script)의 연산을 모두 수행하는 함수이다.

  • 프로토타입

    int prosort_run_script(const char *const script);

  • 파라미터

    파라미터 설명

    script

    연산에 사용할 ProSort의 스크립트(script)이다.

  • 예제

    #include <stdio.h>
#include <stdlib.h>
#include "prosort.h"

int
main(int argc, char **argv)
{
    int rc;
    char *script =
        "DEFREC FIXED,SIZE=256 "
        "MEMORY 500M "
        "INFILE = (x1,100M, x2, 100M, x3, 100M, x4, 100M) "
        "SORT FIELDS=(1,13,AC,A) "
        "OUTFIL FNAMES = xresult ";

    rc = prosort_run_script (script);
    if (rc < 0) {
        fprintf(stderr,"Error[%d]:\n", rc);
        fprintf(stderr,"%s\n", ps_err_code_to_cause(rc));
        fprintf(stderr,"%s\n", ps_err_code_to_action(rc));

        exit (rc);
    }

    return 0;
}

2. prosort_setup

ProSort 실행에 필요한 정보를 초기화한다. 단, prosort_run_script 함수를 사용할 경우에는 prosort_setup 함수를 호출할 필요가 없다.

  • 프로토타입

    typedef int (*callback_func_t)(char **data_buf_addr,
                               int *data_buf_length);

int prosort_setup (const char *prosort_script,
                   callback_func_t *data_fetch_callback_funcs,
                   int data_fetch_callback_func_cnt,
                   void **ptr_prosort_context);

  • 파라미터

    파라미터 설명

    *prosort_script

    ProSort API에서 사용할 스크립트이다.

    *data_fetch_callback_funcs

    MERGE 및 COPY 연산을 할 때에는 데이터를 별도로 입력받지 않고, callback function를 통해 입력 받는다.

    특히, MERGE 연산을 할 때에는 여러 callback function를 입력받을 수 있으므로, callback function의 배열 주소를 파라미터로 받는다.

    data_fetch_callback_func_cnt

    callback function의 개수이다.

    **ptr_prosort_context

    연산 수행을 위해 필요한 컨텍스트(context)의 정보를 얻는다. 생성된 컨텍스트는 다른 API에 적용하여 연산을 수행할 수 있다.

  • 예제

    #include <stdio.h>
#include <stdlib.h>
#include "prosort.h"

static void
print_err_msg(int ec)
{
    fprintf(stderr,"Error[%d]:\n", ec);
    fprintf(stderr,"%s\n", ps_err_code_to_cause(ec));
    fprintf(stderr,"%s\n", ps_err_code_to_action(ec));
    fprintf(stderr,"%s\n", ps_err_get_last_msg());
}

/* 16byte 레코드 */
#define REC_LEN 16

#define RAND (char) (rand() % 24) + 'A'
int
main(int argc, char **argv)
{
    int   i      = 0;
    int   j      = 0;
    int   rc     = 0;

    void *ps_ctx;

    char buf[REC_LEN];
    const char *script = "MEMORY 100M\n"
                         "DATASIZE 100M\n"
                         "DEFREC FIXED, SIZE=16\n"
                         "SORT FIELDS = (1,8,CH,A)\n";

    /* 스크립트 설정 */
    rc = prosort_setup (script, NULL, 0, &ps_ctx);

    if (rc < 0) {
        print_err_msg (rc);
        exit (rc);
    }

    /* 레코드 입력 */
    for (i = 0; i < 100; i++) {

        for (j = 0; j < REC_LEN - 1; j++)
            buf[j] = RAND;
        buf[j] = 0;

        rc = prosort_release_record (ps_ctx, buf, REC_LEN);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
    }
    /* 레코드 입력 완료 */
    prosort_release_end (ps_ctx);

    do {
        char outbuf[REC_LEN];
        char *outbufs[1];
        unsigned int len = REC_LEN;

        outbufs[0] = outbuf;

        rc = prosort_return_record (ps_ctx, outbufs, &len);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
        if (len == 0)
            break;
        printf ("%s\n", outbuf);

    } while (1);

    prosort_end (ps_ctx);
    return 0;
}

3. prosort_setup_with_userexit

모든 입출력 파라미터가 prosort_setup 함수와 동일하다. 단, func_e15, func_e32, func_e35, func_e61 파라미터는 제외이다.

  • 프로토타입

    typedef int (*user_exit_func_t)(const void *rec_addr,
                                const int rec_len,
                                int file_no,
                                void **ret_rec_addr,
                                int *ret_rec_len);

int prosort_setup_with_userexit(const char *prosort_script,
                                callback_func_t *data_fetch_callback_funcs,
                                int data_fetch_callback_func_cnt,
                                user_exit_func_t func_e15,
                                user_exit_func_t func_e32,
                                user_exit_func_t func_e35,
                                user_exit_func_t func_e61,
                                void **ptr_prosort_context);

  • 파라미터

    파라미터 설명

    *prosort_script

    ProSort API에서 사용할 스크립트이다.

    *data_fetch_callback_funcs

    MERGE 및 COPY 연산을 할 때에는 데이터를 별도로 입력받지 않고, callback function를 통해 입력 받는다.

    특히, MERGE 연산을 할 때에는 여러 callback function를 입력받을 수 있으므로, callback function의 배열 주소를 파라미터로 받는다.

    data_fetch_callback_func_cnt

    callback function의 개수이다.

    func_e15

    User Exit Function E15 이다.

    func_e32

    User Exit Function E32 이다.

    func_e35

    User Exit Function E35 이다.

    func_e61

    User Exit Function E61 이다.

    **ptr_prosort_context

    연산 수행을 위해 필요한 컨텍스트의 정보를 얻는다. 생성된 컨텍스트는 다른 API에 적용하여 연산을 수행할 수 있다.

  • 예제

    int func_e15(const void *rec_addr,
             const int rec_len,
             int file_no,
             void **ret_rec_addr,
             int *ret_rec_len)
{
    ...
}

int main(int argc, char **argv)
{
    int rc;
    void *ps_ctx;
    const char *script =
        "DEFREC FIXED,SIZE=150 \n"
        "DATASIZE 2M \n"
        "MEMORY 512M \n"
        "WORKSPACE = (./) \n"
        "SORT FIELDS=(1,2,A),FORMAT=BI \n"
        "INCLUDE COND=(1,2,CH,EQ,C'12',OR,1,2,CH,EQ,C'22',OR,1,2,CH,EQ,C'32') \n"
        "OUTFIL FNAMES=OUT1 \n";

    rc = prosort_setup_with_userexit(script, NULL, 0, func_e15, NULL,
                                     NULL, NULL, &ps_ctx);
    ...
}

4. prosort_release_record

SORT 연산을 할 때 데이터를 레코드별로 입력하는 함수이다.

  • 프로토타입

    int prosort_release_record(void *prosort_context,
                         const char *record,
                         const unsigned int record_length);

  • 파라미터

    파라미터 설명

    *prosort_context

    prosort_setup 함수에서 생성한 컨텍스트를 전달한다.

    *record

    레코드가 있는 주소이다.

    record_length

    레코드의 길이이다.

  • 예제

    #include <stdio.h>
#include <stdlib.h>
#include "prosort.h"

static void
print_err_msg(int ec)
{
    fprintf(stderr,"Error[%d]:\n", ec);
    fprintf(stderr,"%s\n", ps_err_code_to_cause(ec));
    fprintf(stderr,"%s\n", ps_err_code_to_action(ec));
    fprintf(stderr,"%s\n", ps_err_get_last_msg());
}

/* 16byte 레코드 */
#define REC_LEN 16

#define RAND (char) (rand() % 24) + 'A'
int
main(int argc, char **argv)
{
    int   i      = 0;
    int   j      = 0;
    int   rc     = 0;

    void *ps_ctx;

    char buf[REC_LEN];
    const char *script = "MEMORY 100M\n"
                         "DATASIZE 100M\n"
                         "DEFREC FIXED, SIZE=16\n"
                         "SORT FIELDS = (1,8,CH,A)\n";

    /* 스크립트 설정 */
    rc = prosort_setup (script, NULL, 0, &ps_ctx);

    if (rc < 0) {
        print_err_msg (rc);
        exit (rc);
    }

    /* 레코드 입력 */
    for (i = 0; i < 100; i++) {

        for (j = 0; j < REC_LEN - 1; j++)
            buf[j] = RAND;
        buf[j] = 0;

        rc = prosort_release_record (ps_ctx, buf, REC_LEN);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
    }
    /* 레코드 입력 완료 */
    prosort_release_end (ps_ctx);

    do {
        char outbuf[REC_LEN];
        char *outbufs[1];
        unsigned int len = REC_LEN;

        outbufs[0] = outbuf;

        rc = prosort_return_record (ps_ctx, outbufs, &len);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
        if (len == 0)
            break;
        printf ("%s\n", outbuf);

    } while (1);

    prosort_end (ps_ctx);
    return 0;
}

5. prosort_release_end

SORT 연산을 할 때 데이터 입력이 끝났음을 나타내는 함수이다.

  • 프로토타입

    int prosort_release_end(void *prosort_context);

  • 파라미터

    파라미터 설명

    *prosort_context

    prosort_setup 함수에서 생성한 컨텍스트를 전달한다.

  • 예제

    #include <stdio.h>
#include <stdlib.h>
#include "prosort.h"

static void
print_err_msg(int ec)
{
    fprintf(stderr,"Error[%d]:\n", ec);
    fprintf(stderr,"%s\n", ps_err_code_to_cause(ec));
    fprintf(stderr,"%s\n", ps_err_code_to_action(ec));
    fprintf(stderr,"%s\n", ps_err_get_last_msg());
}

/* 16byte 레코드 */
#define REC_LEN 16

#define RAND (char) (rand() % 24) + 'A'
int
main(int argc, char **argv)
{
    int   i      = 0;
    int   j      = 0;
    int   rc     = 0;

    void *ps_ctx;

    char buf[REC_LEN];
    const char *script = "MEMORY 100M\n"
                         "DATASIZE 100M\n"
                         "DEFREC FIXED, SIZE=16\n"
                         "SORT FIELDS = (1,8,CH,A)\n";

    /* 스크립트 설정 */
    rc = prosort_setup (script, NULL, 0, &ps_ctx);

    if (rc < 0) {
        print_err_msg (rc);
        exit (rc);
    }

    /* 레코드 입력 */
    for (i = 0; i < 100; i++) {

        for (j = 0; j < REC_LEN - 1; j++)
            buf[j] = RAND;
        buf[j] = 0;

        rc = prosort_release_record (ps_ctx, buf, REC_LEN);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
    }
    /* 레코드 입력 완료 */
    prosort_release_end (ps_ctx);

    do {
        char outbuf[REC_LEN];
        char *outbufs[1];
        unsigned int len = REC_LEN;

        outbufs[0] = outbuf;

        rc = prosort_return_record (ps_ctx, outbufs, &len);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
        if (len == 0)
            break;
        printf ("%s\n", outbuf);

    } while (1);

    prosort_end (ps_ctx);
    return 0;
}

6. prosort_return_record

연산의 결과를 레코드 건별로 가져오는 함수이다. 출력은 OUTFIL로 인해 여러 개가 나올 수 있으므로, 버퍼의 배열로 가져온다. 0 번째는 SORTOUT (OUTFIL을 수행하지 않은 출력)이 나오며, 스크립트에 정의된 OUTFIL이 순서대로 출력된다.

  • 프로토타입

    int prosort_return_record(void *prosort_context,
                        char **output_buffer,
                        unsigned int *output_buffer_length);

  • 파라미터

    파라미터 설명

    *prosort_context

    prosort_setup 함수에서 생성한 컨텍스트를 전달한다.

    **output_buffer

    출력 레코드를 가져올 버퍼 주소의 배열이다.

    *output_buffer_length

    출력 레코드의 크기를 저장할 배열이다.

  • 예제

    #include <stdio.h>
#include <stdlib.h>
#include "prosort.h"

static void
print_err_msg(int ec)
{
    fprintf(stderr,"Error[%d]:\n", ec);
    fprintf(stderr,"%s\n", ps_err_code_to_cause(ec));
    fprintf(stderr,"%s\n", ps_err_code_to_action(ec));
    fprintf(stderr,"%s\n", ps_err_get_last_msg());
}

/* 16byte 레코드 */
#define REC_LEN 16

#define RAND (char) (rand() % 24) + 'A'
int
main(int argc, char **argv)
{
    int   i      = 0;
    int   j      = 0;
    int   rc     = 0;

    void *ps_ctx;

    char buf[REC_LEN];
    const char *script = "MEMORY 100M\n"
                         "DATASIZE 100M\n"
                         "DEFREC FIXED, SIZE=16\n"
                         "SORT FIELDS = (1,8,CH,A)\n";

    /* 스크립트 설정 */
    rc = prosort_setup (script, NULL, 0, &ps_ctx);

    if (rc < 0) {
        print_err_msg (rc);
        exit (rc);
    }

    /* 레코드 입력 */
    for (i = 0; i < 100; i++) {

        for (j = 0; j < REC_LEN - 1; j++)
            buf[j] = RAND;
        buf[j] = 0;

        rc = prosort_release_record (ps_ctx, buf, REC_LEN);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
    }
    /* 레코드 입력 완료 */
    prosort_release_end (ps_ctx);

    do {
        char outbuf[REC_LEN];
        char *outbufs[1];
        unsigned int len = REC_LEN;

        outbufs[0] = outbuf;

        rc = prosort_return_record (ps_ctx, outbufs, &len);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
        if (len == 0)
            break;
        printf ("%s\n", outbuf);

    } while (1);

    prosort_end (ps_ctx);
    return 0;
}

7. prosort_end

모든 연산에 사용한 리소스를 반환하는 함수이다.

  • 프로토타입

    int prosort_end(void *prosort_context);

  • 파라미터

    파라미터 설명

    *prosort_context

    prosort_setup 함수에서 생성한 컨텍스트를 전달한다.

  • 예제

    #include <stdio.h>
#include <stdlib.h>
#include "prosort.h"

static void
print_err_msg(int ec)
{
    fprintf(stderr,"Error[%d]:\n", ec);
    fprintf(stderr,"%s\n", ps_err_code_to_cause(ec));
    fprintf(stderr,"%s\n", ps_err_code_to_action(ec));
    fprintf(stderr,"%s\n", ps_err_get_last_msg());
}

/* 16byte 레코드 */
#define REC_LEN 16

#define RAND (char) (rand() % 24) + 'A'
int
main(int argc, char **argv)
{
    int   i      = 0;
    int   j      = 0;
    int   rc     = 0;

    void *ps_ctx;

    char buf[REC_LEN];
    const char *script = "MEMORY 100M\n"
                         "DATASIZE 100M\n"
                         "DEFREC FIXED, SIZE=16\n"
                         "SORT FIELDS = (1,8,CH,A)\n";

    /* 스크립트 설정 */
    rc = prosort_setup (script, NULL, 0, &ps_ctx);

    if (rc < 0) {
        print_err_msg (rc);
        exit (rc);
    }

    /* 레코드 입력 */
    for (i = 0; i < 100; i++) {

        for (j = 0; j < REC_LEN - 1; j++)
            buf[j] = RAND;
        buf[j] = 0;

        rc = prosort_release_record (ps_ctx, buf, REC_LEN);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
    }
    /* 레코드 입력 완료 */
    prosort_release_end (ps_ctx);

    do {
        char outbuf[REC_LEN];
        char *outbufs[1];
        unsigned int len = REC_LEN;

        outbufs[0] = outbuf;

        rc = prosort_return_record (ps_ctx, outbufs, &len);
        if (rc < 0) {
            print_err_msg (rc);
            exit (rc);
        }
        if (len == 0)
            break;
        printf ("%s\n", outbuf);

    } while (1);

    prosort_end (ps_ctx);
    return 0;
}

8. prosort_get_error_number

에러가 발생했을 때 에러 번호를 가져오는 함수이다.

  • 프로토타입

    int prosort_get_error_number(void *prosort_context);

  • 파라미터

    파라미터 설명

    *prosort_context

    prosort_setup 함수에서 생성한 컨텍스트를 전달한다.

  • 예제

    int main(int argc, char **argv)
{
    int rc;
    void *ps_ctx;
    const char *script =
        "DEFREC FIXED,SIZE=150 \n"
        "DATASIZE 2M \n"
        "MEMORY 512M \n"
        "WORKSPACE = (./) \n"
        "SORT FIELDS=(1,2,A),FORMAT=BI \n"
        "INCLUDE COND=(1,2,CH,EQ,C'12',OR,1,2,CH,EQ,C'22',OR,1,2,CH,EQ,C'32') \n"
        "OUTFIL FNAMES=OUT1 \n";

    rc = prosort_setup(script, NULL, 0, &ps_ctx);
    if(rc < 0) {
        fprintf(stderr, "Error number is %d\n", prosort_get_error_number(ps_ctx));
    }
    ...
}

9. prosort_get_error_message

에러가 발생했을 때 에러 메시지를 가져오는 함수이다.

  • 프로토타입

    int prosort_get_error_message(void *prosort_context,
                            char *error_message_buffer,
                            unsigned int *error_message_length);

  • 파라미터

    파라미터 설명

    *prosort_context

    prosort_setup 함수에서 생성한 컨텍스트를 전달한다.

    *error_message_buffer

    에러 메시지를 가져올 버퍼의 주소이다.

    *error_message_length

    에러 메시지의 길이이다.

  • 예제

    #define ERR_MSG_MAXLEN 1024
int main(int argc, char **argv)
{
    int rc;
    void *ps_ctx;
    char *err_msg;
    unsigned int err_msg_len;
    const char *script =
        "DEFREC FIXED,SIZE=150 \n"
        "DATASIZE 2M \n"
        "MEMORY 512M \n"
        "WORKSPACE = (./) \n"
        "SORT FIELDS=(1,2,A),FORMAT=BI \n"
        "INCLUDE COND=(1,2,CH,EQ,C'12',OR,1,2,CH,EQ,C'22',OR,1,2,CH,EQ,C'32') \n"
        "OUTFIL FNAMES=OUT1 \n";
    err_msg = (char *)malloc(sizeof(char) * ERR_MSG_MAXLEN);
    err_msg_len = ERR_MSG_MAXLEN;

    rc = prosort_setup(script, NULL, 0, &ps_ctx);
    if(rc < 0) {
        prosort_get_error_message(ps_ctx, err_msg, &err_msg_len);
        fprintf(stderr, "Error message is %s\n", err_msg);
    }
    ...
}